From f4fa70c00577cc1ff58cf32e1f62f65f09d819f6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?L=C3=A9on=20Avic=20Simmons?= <Avicennasis@gmail.com>
Date: Wed, 19 Aug 2026 02:08:40 -0400
Subject: [PATCH] docs: fix references to things that do not exist

Three unrelated accuracy problems, all found by checking documentation
against the tree.

1. README describes a `_config/` folder that does not exist

   README.md:75 puts `_config/` in the canonical workspace layout and
   README.md:82 calls it a Layer 3 location. There is no `_config/`
   directory anywhere in the repo:

     $ find . -type d -name '_config' | wc -l
     0

   The real Layer 3 config folders are `brand-vault/` (script-to-animation,
   voice-driven-animation) and `design-system/` (course-deck-production),
   which is what _core/CONVENTIONS.md:25 already says. Updated the README to
   match the convention the workspaces actually follow.

2. conventions-reference.md skips Pattern 8

   The file enumerates Patterns 1-7 and 9-15. Pattern 8 (Questionnaire
   Design) is missing. This matters because stage 01-discovery loads this
   file as "Full file" to "know the ICM patterns", and stage
   04-questionnaire-design is the stage that needs Pattern 8 most. Added the
   entry in the same one-line-summary-plus-pointer style as its neighbours.

3. .gitignore has no __pycache__ rule

   The repo ships 15 Python scripts across the bundled pptx, elevenlabs and
   whisper skills. Running any of them leaves untracked __pycache__/
   directories in git status. Added __pycache__/ and *.pyc.

Verified: 0 remaining `_config` references in the README against 3 real
config dirs; Patterns 1-15 all present in conventions-reference.md; and the
gitignore rule tested by creating a real __pycache__ directory and
confirming git status stays clean.
---
 .gitignore                                                    | 4 ++++
 README.md                                                     | 4 ++--
 .../workspace-builder/references/conventions-reference.md     | 2 ++
 3 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/.gitignore b/.gitignore
index 65dacdd..07f73f6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -12,6 +12,10 @@ workspaces/workspace-builder/stages/*/output/*
 # Node dependencies
 node_modules/
 
+# Python bytecode
+__pycache__/
+*.pyc
+
 # OS files
 .DS_Store
 Thumbs.db
diff --git a/README.md b/README.md
index beb5552..d1d1589 100644
--- a/README.md
+++ b/README.md
@@ -72,14 +72,14 @@ workspace/
       CONTEXT.md
       references/
       output/
-  _config/                  # Layer 3: brand, voice, design system
+  brand-vault/              # Layer 3: brand, voice, design system (name varies)
   shared/                   # Layer 3: cross-stage resources
   skills/                   # Layer 3: bundled domain knowledge
   setup/
     questionnaire.md        # One-time onboarding
 ```
 
-The numbering encodes execution order. The folder boundaries enforce separation of concerns. The `output/` directories are the Layer 4 handoff points: the output of stage 01 becomes available as input to stage 02. If a human edits a file in `01-research/output/` before running stage 02, the agent picks up the edited version. The `references/` directories and `_config/` folder hold Layer 3 material -- stable knowledge that persists across runs.
+The numbering encodes execution order. The folder boundaries enforce separation of concerns. The `output/` directories are the Layer 4 handoff points: the output of stage 01 becomes available as input to stage 02. If a human edits a file in `01-research/output/` before running stage 02, the agent picks up the edited version. The `references/` directories and the workspace-level config folder (`brand-vault/`, `design-system/`) hold Layer 3 material -- stable knowledge that persists across runs.
 
 Layer 2 is the control point. Each stage contract includes an Inputs table that specifies exactly which files from Layers 3 and 4 to load, and which sections of those files are relevant. Without this scoping, an agent would either load everything or guess. The Inputs table makes the selection explicit, editable, and auditable.
 
diff --git a/workspaces/workspace-builder/references/conventions-reference.md b/workspaces/workspace-builder/references/conventions-reference.md
index a918f4e..5b19efa 100644
--- a/workspaces/workspace-builder/references/conventions-reference.md
+++ b/workspaces/workspace-builder/references/conventions-reference.md
@@ -24,6 +24,8 @@ The most important conventions for building a new workspace:
 
 - **Tool prerequisites**: If stages need system-level tools (Node.js, Python, LibreOffice), write setup guides in the relevant stage's references/ folder. See "Pattern 7: Tool Prerequisites" in `/_core/CONVENTIONS.md`.
 
+- **Questionnaire design**: Onboarding questionnaires configure the production system, not a specific run. Flat, all at once, system-level only. Derive fields where possible instead of asking. See "Pattern 8: Questionnaire Design" in `../../../_core/CONVENTIONS.md`.
+
 - **Bundled skills**: Copy relevant Claude Code skills into skills/ folder. Skills provide domain knowledge (APIs, best practices, code examples) and can replace custom reference docs. Discover local skills and search GitHub during Stage 01. See "Pattern 9: Bundled Skills" in `/_core/CONVENTIONS.md`.
 
 - **Specs are contracts**: Specification stages define WHAT and WHEN, not HOW. No component names, frame numbers, or prop definitions in specs. The build stage has creative freedom within the quality floor. See "Pattern 10: Specs Are Contracts" in `/_core/CONVENTIONS.md`.