SuffolkLITLab · nonprofittechy · Aug 23, 2026 · Aug 23, 2026
diff --git a/docs/archive/bootcamp.md b/docs/archive/bootcamp.md
@@ -46,7 +46,7 @@ After signing up, you should have received invites to our docassemble server (ht
 
 Resources from the session:
 
-* [Running templates through the Weaver](../authoring/weaver_overview.md)
+* [Building interviews with the Weaver](../authoring/weaver/overview.md)
 * [Labeling PDF variables](../authoring/pdf_templates.md)
 * [Naming Variables Quick Reference](../authoring/doc_vars_reference.md)
 * [The LIST taxonomy](https://taxonomy.legal/)

diff --git a/docs/assets/editor_find_replace.png b/docs/assets/editor_find_replace.png
diff --git a/docs/assets/editor_github_publish.png b/docs/assets/editor_github_publish.png
diff --git a/docs/assets/editor_main_interview_screen.png b/docs/assets/editor_main_interview_screen.png
diff --git a/docs/assets/editor_order_builder.png b/docs/assets/editor_order_builder.png
diff --git a/docs/assets/editor_project_selector.png b/docs/assets/editor_project_selector.png
diff --git a/docs/assets/editor_question_library.png b/docs/assets/editor_question_library.png
diff --git a/docs/assets/editor_raw_yaml_view.png b/docs/assets/editor_raw_yaml_view.png
diff --git a/docs/assets/editor_screen_preview.png b/docs/assets/editor_screen_preview.png
diff --git a/docs/assets/editor_templates_documents.png b/docs/assets/editor_templates_documents.png
diff --git a/docs/assets/editor_validation_drawer.png b/docs/assets/editor_validation_drawer.png
diff --git a/docs/authoring/ai_checklist_quality_publish.md b/docs/authoring/ai_checklist_quality_publish.md
@@ -20,4 +20,4 @@ Related guides (canonical details):
 - [Coding style for YAML translation](../coding_style/yaml_translation.md)
 - [Writing good questions](../style_guide/question_style_overview.md)
 - [Editing your interview](customizing_interview.md)
-- [Metadata for publishing generated YAML interviews](weaver_code_anatomy.md#interview-metadata-and-metadata-for-publishing-on-courtformsonline)
+- [Metadata and publishing guide](weaver/publishing_and_github.md)
diff --git a/docs/authoring/ai_checklist_weaver_editing.md b/docs/authoring/ai_checklist_weaver_editing.md
@@ -17,7 +17,8 @@ Use this checklist after labels are ready and you are generating a draft intervi
 
 Related guides (canonical details):
 
-- ["Weaving" your form into a draft interview](weaver_overview.md)
+- [The Assembly Line Weaver](weaver/overview.md)
 - [Editing your interview](customizing_interview.md)
-- [Writing your own review screen](writing_review_screen.md)
+- [Writing a review screen](writing_review_screen.md)
+- [Review screen synchronization in the Weaver](weaver/review_screens.md)
 - [Dynamic phrases based on prior answers](dynamic_phrasing_based_on_values.md)
diff --git a/docs/authoring/combining_interviews.md b/docs/authoring/combining_interviews.md
@@ -5,11 +5,11 @@ title: Combining multiple interviews
 
 # Combining multiple docassemble interviews
 
-When you use the AssemblyLine Weaver to create an interview, it gives you a complete, standalone interview out of the box (like you see in [docassemble-ALWeaver](https://github.com/SuffolkLITLab/docassemble-ALWeaver)). But often, you need to combine several different forms or interviews into one unified, seamless user experience. 
+When you use the [AssemblyLine Weaver](weaver/overview.md) to create an interview, it gives you a complete, standalone interview out of the box (like you see in [docassemble-ALWeaver](https://github.com/SuffolkLITLab/docassemble-ALWeaver)). But often, you need to combine several different forms or interviews into one unified, seamless user experience. 
 
 For example, you might want to combine a "Petition for Guardianship" and a "Motion for Temporary Guardian" into a single flow, or bundle multiple housing code complaint forms.
 
-This tutorial walks you through the step-by-step process of taking multiple standalone ALWeaver interviews and combining them.
+This tutorial walks you through the step-by-step process of taking multiple standalone Weaver interviews and combining them.
 
 ## Key concepts
 

diff --git a/docs/authoring/customizing_interview.md b/docs/authoring/customizing_interview.md
@@ -5,61 +5,51 @@ sidebar_label: Editing your interview
 slug: customizing_interview
 ---
 
-## Edit your completed draft interview in the docassemble playground
+## Editing your interview in the Weaver or Playground
+
+You can edit and refine your interview either visually in the [Assembly Line Weaver](weaver/overview.md) or directly in the Docassemble Playground code editor.
+
+:::tip Visual editing with the Weaver
+The [Assembly Line Weaver](weaver/overview.md) allows you to edit question screens, reorder flow steps, preview screens across devices, configure document bundles, and run safe variable refactorings without manually writing YAML:
+* [Designing question screens and fields](weaver/screens_and_fields.md)
+* [Live screen previews](weaver/screen_previews.md)
+* [Sequencing flow with the interview order builder](weaver/interview_order.md)
+* [Configuring document bundles and templates](weaver/document_bundles.md)
+* [Review screen synchronization](weaver/review_screens.md)
+* [Diagnostics and safe refactoring](weaver/diagnostics_and_refactoring.md)
+:::
 
-While the Weaver is a menu-driven, step-by-step process, you'll make further
-edits in the Playground. In the playground, you can directly edit the
-[YAML](../docassemble_intro/yaml) text to:
+If you prefer to edit the raw [YAML](../docassemble_intro/yaml) text directly in the Playground or your local code editor, you can:
 
 1. Change the wording of questions
-1. Change the datatype of questions and add show/hide logic
-1. Edit the order screens appear in
-1. Add conditional and branching logic
-1. Add new variables, such as variables calculated by code
+2. Change the datatype of questions and add show/hide logic
+3. Edit the order screens appear in
+4. Add conditional and branching logic
+5. Add new variables, such as variables calculated by code
 
-Save your work frequently, and don't be intimidated. For the most part,
-many changes can be understood by reading the text and then experimenting.
+Save your work frequently, and don't be intimidated. For the most part, many changes can be understood by reading the text and experimenting.
 
-This pages offers information about making some common, simple edits.
-You may also want to take this time to read through the materials in
-[Introduction to docassemble](../docassemble_intro/introduction-to-docassemble)
-about the underlying docassemble platform and how it works.
+This page offers information about making common manual YAML edits. You may also want to take this time to read through the materials in [Introduction to docassemble](../docassemble_intro/introduction-to-docassemble) about the underlying Docassemble platform.
 
-## Double-check that you got things right in the Weaver stage
+## Double-check that you got things right in the labeling stage
 
-Some common mistakes, like typos in the labels, can lead to a lot of extra work. 
-If you see "extra" questions appear, it's possible that you didn't get the names 
-quite right, perhaps something as simple as a typo.
+Some common mistakes, like typos in the labels, can lead to a lot of extra work. If you see "extra" questions appear, it's possible that you didn't get the names quite right, perhaps something as simple as a typo. Use the [Weaver diagnostics drawer](weaver/diagnostics_and_refactoring.md) to detect missing or mismatched variables automatically.
 
 ## Work towards a readable, usable interview
 
-You should also take this chance to review our guidance about
-[writing good questions](../style_guide/question_style_overview.md). While you edit
-your interview, work steadily to make it better.
-
-## Getting the draft into your playground
+You should also take this chance to review our guidance about [writing good questions](../style_guide/question_style_overview.md). While you edit your interview, work steadily to make it better.
 
-When you have finished using the Weaver, download your package. This will put a
-.zip file in the Downloads folder on your computer.
+## Working with Playground projects
 
-:::warning If you are using Safari on a Mac OS computer
-Safari, by default, will turn your downloaded package into
-a folder on your PC.
+The Weaver and Docassemble Playground share the same project files:
 
-Before downloading the package, turn off that behavior:
+1. In the Playground or the Weaver project selector, select or create your project.
+2. Changes made in the Weaver are saved directly to your Playground files and can be opened in either environment at any time.
 
-1. open Safari 
-1. click Preferences
-1. under the General tab, uncheck the option **Open 'safe' files after downloading**
-:::
-
-First, create a new "Project" in your playground. Using projects will
-help you keep your docassemble code organized.
+If you are using the legacy wizard or an exported `.zip` package, you can upload it to the Playground's **Packages** folder.
 
 ![playground | projects ](../assets/playground_projects.png)
 
-Next, upload this file to the docassemble playground's `Packages` folder.
-
 ![Folders | Packages ](../assets/playground_packages_menu.png)
 
 ## How to edit your interview

diff --git a/docs/authoring/doc_vars_reference.md b/docs/authoring/doc_vars_reference.md
@@ -391,8 +391,9 @@ Getting things right at the beginning can save you a lot of time and effort.
 
 However, you can always edit your template later. When you make changes to your
 template, you do not need to run it through the Weaver again. You can upload
-your edited template directly to the docassemble playground's templates folder.
+your edited template directly in the [Weaver's Templates tab](weaver/document_bundles.md) or the Docassemble Playground.
 
 ## See also
 
+- [The Assembly Line Weaver](weaver/overview.md)
 - [List of reserved variable names](../components/AssemblyLine/reserved_keywords.md)
diff --git a/docs/authoring/pdf_templates.md b/docs/authoring/pdf_templates.md
@@ -133,7 +133,7 @@ with the same field names, for example, in a document bundle, you still may have
 
 ## Quality control checklist
 
-Many of the below checkbox items can be verified by uploading the PDF to the [Weaver](https://github.com/SuffolkLITLab/docassemble-ALWeaver), 
+Many of the below checkbox items can be verified by uploading the PDF to the [Weaver](weaver/overview.md), 
 installed on your own docassemble server. When you upload a PDF to the Weaver, it will try filling in all of the PDF's fields with dummy data,
 allowing for a quick visual inspection.
 

diff --git a/docs/authoring/weaver/authoring_checklist.md b/docs/authoring/weaver/authoring_checklist.md
@@ -0,0 +1,67 @@
+---
+id: weaver_authoring_checklist
+title: |
+  Authoring checklist: start to finish
+sidebar_label: |
+  Authoring checklist
+slug: authoring_checklist
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+Use this comprehensive pre-flight checklist before handing off your interview for legal review, user testing, or production launch.
+
+---
+
+## 1. Document template preparation
+
+- [ ] **Labels Verified**: All fields in DOCX and PDF templates are labeled with standard [AssemblyLine variable conventions](../doc_vars_reference.md).
+- [ ] **Clean Filenames**: Template files have clean, descriptive names without draft suffixes (e.g. `motion_to_dismiss.docx`).
+- [ ] **Overflow Safeguards**: Multi-line narrative text areas in PDF templates have matching overflow addenda or auto-scaling enabled.
+
+---
+
+## 2. Project setup and metadata
+
+- [ ] **Project Created**: Playground project initialized in the Weaver.
+- [ ] **Metadata Defined**: The `metadata:` block includes title, short title, description, author names, and relevant legal topic tags.
+- [ ] **Standard Objects Declared**: `ALPeopleList` declared for `users` and `other_parties` with appropriate quantity rules.
+
+---
+
+## 3. Question screens and plain language
+
+- [ ] **Readable Headings**: Screen titles and subquestions are written in plain, accessible language (5th-to-8th grade reading level).
+- [ ] **Input Field Types**: Every field uses the appropriate datatype (e.g., date pickers for dates, currency for dollar amounts, yes/no for booleans).
+- [ ] **Required vs Optional**: Required toggles are properly set, and optional fields are wrapped in conditional logic in templates.
+- [ ] **Help Text Added**: Unfamiliar legal terms are explained using field help popovers.
+
+---
+
+## 4. Interview order and flow
+
+- [ ] **Logical Step Hierarchy**: Question screens, loops (`.gather()`), conditional branches (`if/else`), and progress indicators (`set_progress`) are sequenced in the Order Builder.
+- [ ] **Off-Ramp Screens**: Exit screens are in place for users who do not qualify or who should not proceed.
+- [ ] **Review Screen Enabled**: A `review:` screen allows users to inspect and edit their answers before compiling final documents.
+
+---
+
+## 5. Document bundles and assembly
+
+- [ ] **Document Bundles Configured**: `ALDocument` and `ALDocumentBundle` definitions are ordered and labeled cleanly.
+- [ ] **Conditional Inclusion Tested**: Documents that should only appear under certain conditions (e.g. fee waivers, instructions) have verified conditional expressions.
+
+---
+
+## 6. Diagnostics and quality verification
+
+- [ ] **Zero Validation Errors**: The **Errors & Warnings** drawer shows no missing IDs, duplicate blocks, or undefined variables.
+- [ ] **Live End-to-End Test**: Successfully completed a full test run of the interview using **Open interview**, generating and downloading sample court documents.
+- [ ] **Mobile and Desktop Tested**: Screen layouts and touch targets verified in live screen preview on mobile, tablet, and desktop viewports.
+
+---
+
+## 7. Version control and publishing
+
+- [ ] **Committed to GitHub**: Code pushed to the appropriate GitHub organization repository with a clean commit message.
diff --git a/docs/authoring/weaver/diagnostics_and_refactoring.md b/docs/authoring/weaver/diagnostics_and_refactoring.md
@@ -0,0 +1,63 @@
+---
+id: weaver_diagnostics_and_refactoring
+title: |
+  Diagnostics, safe refactoring, and YAML code view
+sidebar_label: |
+  Diagnostics and refactoring
+slug: diagnostics_and_refactoring
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+The Weaver includes comprehensive static analysis tools, project-wide safe variable refactoring, and an embedded CodeMirror 6 YAML editor to ensure your interview code remains clean, error-free, and maintainable.
+
+---
+
+## Real-time validation and diagnostics
+
+The bottom **Errors & Warnings** drawer continuously analyzes your interview as you make changes:
+
+![Validation and Error Diagnostics Drawer](../../assets/editor_validation_drawer.png)
+
+The linter automatically checks for:
+* **Duplicate or Missing Block IDs**: Flags blocks that share an ID or omit an essential `id:` tag.
+* **Undefined Variables**: Detects references in questions, review screens, or order logic that have no matching field definitions or object declarations.
+* **Template Field Mismatches**: Warns if a variable is used in a DOCX or PDF template but is missing from your question screens.
+
+For plain-language and style review, use the validation drawer's **Style check** action separately — it is not part of the always-on drawer checks and calls an AI-assisted review of your question wording.
+
+---
+
+## Project-wide find and replace with safe variable refactoring
+
+Renaming a variable across a complex project with a simple text search-and-replace often causes unintended side effects—corrupting user-facing labels, subquestions, or comments.
+
+Click the magnifying-glass icon next to the project selector in the left rail to open **Find and replace**:
+
+![Project-Wide Find and Replace](../../assets/editor_find_replace.png)
+
+### Safe variable refactoring mode
+* **AST & Structure Awareness**: Uses Python Abstract Syntax Tree (AST) parsing and YAML stream analysis to distinguish between actual variable references and identical words in human-facing text.
+* **Multi-File Scope**: Finds and updates occurrences across YAML interviews, DOCX Jinja2 templates, and Python modules simultaneously.
+* **Selective Replacement**: Displays a list of matches with surrounding context and checkboxes, allowing you to choose exactly which occurrences to replace.
+
+---
+
+## Full raw YAML view
+
+For power users who prefer to inspect or edit raw code directly, click **More** $\to$ **YAML source**:
+
+![Full Raw YAML View in CodeMirror 6](../../assets/editor_raw_yaml_view.png)
+
+The built-in CodeMirror 6 editor provides:
+* Full syntax highlighting for Docassemble YAML, Mako templates, and embedded Python expressions.
+* Code folding, line numbering, and bracket matching.
+* **Two-Way Synchronization**: Any valid edits made in the raw YAML view are parsed and updated in the visual block outline as soon as you return to the block editor.
+
+---
+
+## Next steps
+
+* Push your interview to GitHub in [Publishing and version control with GitHub](publishing_and_github.md).
+* Review the [Authoring checklist](authoring_checklist.md) before publishing.
diff --git a/docs/authoring/weaver/document_bundles.md b/docs/authoring/weaver/document_bundles.md
@@ -0,0 +1,60 @@
+---
+id: weaver_document_bundles
+title: |
+  Configuring document bundles and templates
+sidebar_label: |
+  Document bundles and templates
+slug: document_bundles
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+In the **Templates** view of the Weaver, clicking **Document setup** opens the document assembly manager. This interface controls which templates are compiled, how multiple documents are bundled together, and the conditional rules that govern when specific documents are generated.
+
+![Templates and Document Bundles Setup](../../assets/editor_templates_documents.png)
+
+---
+
+## Working with template files
+
+You can upload both DOCX and PDF templates into your project:
+
+1. Click **Upload** in the left sidebar of the Templates tab to add a new labeled DOCX or PDF file.
+2. The Weaver analyzes the template's Jinja2 tags or PDF form fields and registers them in the project.
+
+---
+
+## Understanding document bundles (`ALDocumentBundle`)
+
+An `ALDocumentBundle` combines one or more `ALDocument` items into a unified downloadable packet (such as a single PDF containing a Motion, an Affidavit of Indigency, and a Certificate of Service):
+
+```yaml
+objects:
+  - motion_to_dismiss_doc: ALDocument.using(title="Motion to Dismiss", filename="motion_to_dismiss.docx", enabled=True)
+  - instructions_doc: ALDocument.using(title="Filing Instructions", filename="instructions.docx", enabled=include_instructions)
+  - bundle: ALDocumentBundle.using(title="Main Filing Package", elements=['motion_to_dismiss_doc', 'instructions_doc'], enabled=True)
+```
+
+---
+
+## Document inclusion rules
+
+For each document in your bundle, you can configure when it should be compiled:
+
+* **Always**: The document is always generated and included in the final download package.
+* **Never**: The document is excluded by default (useful for draft or reference templates).
+* **Custom (Condition)**: Enter a Python condition (e.g. `include_instructions` or `user_has_fee_waiver`). The document will only be assembled when this expression evaluates to `True`.
+
+---
+
+## Reordering documents in the bundle
+
+Use the up (<i class="fa-solid fa-arrow-up"></i>) and down (<i class="fa-solid fa-arrow-down"></i>) buttons next to each document entry to change the order in which documents are assembled and merged into the final packet.
+
+---
+
+## Next steps
+
+* Add a summary review screen for user verification in [Review screen synchronization](review_screens.md).
+* Check your interview for errors in [Diagnostics, refactoring, and YAML code view](diagnostics_and_refactoring.md).