@freetesh/zeno 0.0.0-stage → 0.7.0

package/skills/ask/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: ask
+description: Answer a question from the wiki only. Searches .context/wiki/ pages and returns a cited answer with [[wikilinks]] to every page used. Never reads .context/raw/ directly — synthesis must be written down. Usage `/ask <question>`.
+---
+
+You are answering a question using ONLY `.context/wiki/` as the knowledge source.
+
+Question: `$ARGUMENTS`
+
+## Steps
+
+1. **Search first.** If the `qmd` MCP tool is available, run a `query` for the question against this product's wiki collection (`<product>-wiki`). Its hits are the first candidates.
+
+2. **Read `.context/wiki/index.md`** and **identify candidate pages** by matching the question against page titles, IDs, and the index entries. Prefer:
+   - `entity` pages for "what is the value / price / name of X"
+   - `synthesis` pages for cross-cutting summaries (use these before chasing individual entities)
+   - `concept` pages for "why" or "what does X mean" questions
+   - `surface` pages for "what does this screen do"
+   - `flow` pages for "how does the user get from A to B"
+   - `decision` pages for "why did we choose X over Y"
+
+3. **Read the candidate pages.** Follow `[[wikilinks]]` one hop if the answer is incomplete. Stop at two hops — if you need three, the wiki is missing a synthesis page; say so.
+
+4. **Answer the question** in the product's own voice:
+   - Follow the copy rules in the root `CLAUDE.md` — plain words, short sentences, active voice.
+   - Write numbers, prices and dates the way the product writes them to a user.
+   - Cite every claim with a `[[wikilink]]` to the source page.
+   - If two pages disagree, surface the contradiction explicitly — don't pick a winner. `/wiki-lint` will flag it; the user resolves it via `/decision`.
+
+5. **If the wiki cannot answer:**
+   - Say so plainly.
+   - List the pages you checked.
+   - Suggest what's missing: "no entity page exists for `<thing>`", "no synthesis page combines `<X>` and `<Y>`", etc.
+   - Recommend the user run `/ingest <raw-source>` to fill the gap.
+
+## Rules
+
+- **Never read `.context/raw/` or `.context/designs/` from this skill.** If the answer requires raw inspection, refuse and recommend `/ingest`.
+- **Never invent facts.** If a canonical value isn't in an `entity` page, say "not in the wiki".
+- **Every cited page must actually exist.** Don't fabricate a `[[wikilink]]` to make the answer look authoritative.
+- A page with `status: superseded` is not canonical — follow `superseded-by` to the current page.
+- A page with `last-verified` > 90 days is stale — flag it in the answer ("last verified 2025-11-04 — may be out of date").

package/skills/decision/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: decision
+description: Record a product or technical decision as a new ADR page in .context/wiki/decisions/. Usage `/decision <title> — <body>`.
+---
+
+You are logging a decision as a new `.context/wiki/decisions/<YYYY-MM-DD>-<slug>.md` page.
+
+Decision to record: `$ARGUMENTS`
+
+## Steps
+
+1. Read the wiki schema (`../../standards/wiki-schema.md`, relative to this skill) § "`decision`" for the frontmatter and the required sections. If `.context/wiki/decisions/` already holds pages, open a recent one and match it.
+
+2. Parse `$ARGUMENTS`:
+   - If it contains ` — ` (em-dash with spaces), split on the first occurrence: left = title, right = body.
+   - Otherwise treat the whole string as the title; body = "(no detail provided)".
+
+3. Derive the filename:
+   - Date = today's `currentDate` from the session context (`YYYY-MM-DD`).
+   - Slug = kebab-case of the title, lower-cased, alphanumerics + hyphens only, ≤ 60 chars.
+   - Path = `.context/wiki/decisions/<date>-<slug>.md`. If a file at that path already exists, append `-2`, `-3`, etc.
+
+4. Write the new ADR with the standard frontmatter and the body the user provided. Do not summarise or shorten the body.
+
+5. Add the page to `.context/wiki/index.md` under Decisions.
+
+6. Confirm: `decision logged: "<title>" → <path>`.
+
+## Rules
+
+- One decision per file. Never append to an existing ADR.
+- Do not edit any other wiki page in the same command — if cross-references are needed, surface them in the body as `[[wikilinks]]`, but leave the target pages alone.
+- The wiki is the only source of truth for decisions. There is no monolithic decision log.

package/skills/ingest/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: ingest
+description: Read a raw source (wireframe, meeting note, research doc) and draft the wiki page(s) that summarise it. Adds frontmatter, [[wikilinks]], and updates .context/wiki/index.md. Usage `/ingest <path-to-raw-file>`.
+---
+
+You are ingesting a raw source into the wiki at `.context/wiki/`.
+
+Source to ingest: `$ARGUMENTS`
+
+## Steps
+
+1. **Read the wiki schema (`../../standards/wiki-schema.md`, relative to this skill) first.** It defines page types, frontmatter, required sections, ID conventions, and lint rules. Every page you write must conform.
+
+2. **Read the raw source** at the path in `$ARGUMENTS`. Accepted: anything under `.context/raw/` or `.context/designs/`, and application source in this repository. Refuse paths outside the repo.
+
+3. **Classify** the source into one or more wiki page types:
+   - HTML wireframe → `surface` page
+   - Decision note → `decision` page
+   - Research doc / interview → typically `concept` pages (split if it covers multiple ideas), or one `synthesis` page for a brief that draws a conclusion
+   - A new tier / product / canonical value → `entity` page
+   - A user journey description → `flow` page
+   - Don't force one source into one page — a meeting note can produce multiple pages.
+
+4. **For each page you will create:**
+   - Pick the ID per the wiki schema (`../../standards/wiki-schema.md`, relative to this skill) § "ID conventions". IDs are uppercase, dot-separated, never change.
+   - Pick the filename: the slug portion of the ID, lowercase, kebab-case, `.md` extension.
+   - Check whether the page already exists. If yes, **update** rather than overwrite: preserve `id`, `supersedes`, `superseded-by`; refresh `last-verified` to today.
+   - Use the required sections for that page type — verbatim from the wiki schema (`../../standards/wiki-schema.md`, relative to this skill). Missing a required section is a lint failure.
+   - Fill `Related` with at least two `[[wikilinks]]`. A link to a page that doesn't exist yet is OK — `/wiki-lint` will flag it as a TODO.
+   - List the source path under `Sources`, so a future `/wiki-lint` can tell which raw files nothing has read.
+
+5. **Update `.context/wiki/index.md`:** add the new page under the right type heading, in alphabetical order by slug. Don't reformat existing entries.
+
+6. **Leave the source where it is.** `.context/raw/` is immutable: a source is "processed" when a wiki page lists it under `Sources`, not when it moves.
+
+7. **Report**: list each page created or updated with its ID and path. Flag any `[[wikilinks]]` to non-existent pages as "TODO targets".
+
+## Rules
+
+- Never edit anything under `.context/raw/` or `.context/designs/`.
+- Never delete or rename an existing wiki page from this skill — use a `decision` page to log a rename, then run again.
+- Never invent canonical values. If the source has a price/string/enum, copy it verbatim; if it's ambiguous, ask the user before writing.
+- Follow the copy rules from the root `CLAUDE.md` for any user-facing strings you transcribe.
+- Today's date is in the session context — use it for `last-verified`.

package/skills/standards/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: standards
+description: Load the standards that cover the work before doing it — the repo's design rules, code standards, .context layout, wiki schema, agent contract, and any team-specific rules. Use before creating or changing designs, code, .context/ files, wiki pages, store listings, or anything a team rule might govern, and when asked "what are the rules for…".
+---
+
+# Load the standards that apply
+
+1. List them: run `zeno standards` in the repo. It prints every standard that
+   applies — zeno's defaults, then the team's and the repo's own (a team file
+   with the same name replaces zeno's). If the `zeno` CLI is not installed, use
+   the files in `../../standards/` (relative to this skill).
+2. Read only the ones that cover this work: designs, code, `.context/`, wiki,
+   listing, secrets — judge from the file names, then their first lines.
+3. Follow them. Where two disagree, the more specific one (the repo's, then the
+   team's, then zeno's) wins; say which one you followed.
+4. Before calling the work done, run `zeno check` and report its result.

package/skills/weigh/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: weigh
+description: Decision gate run BEFORE acting on a non-trivial request in a product repo — a new feature, screen or product, a new dependency or library, a migration or rewrite, a schema, money, pricing or store change, a release or deploy, deleting something, or any change touching more than one file or more than one product. Weighs the request against the zeno constitution, the product's wiki and ADRs, existing features and tasks, cost vs value, and writing less code, then returns do it / do it differently / push back with citations. Also use when the user types /weigh or asks "should we…", "is it worth…", "does this make sense".
+---
+
+# Weigh before acting
+
+You are deciding whether and how to do a request — not doing it yet.
+Request: `$ARGUMENTS` (empty = the user's latest request in this conversation).
+
+## Skip the gate when it is trivial
+
+Answer and act directly, with no verdict block, when **all** are true: one file,
+no new dependency, no schema / money / store / release / delete, and the change is
+fully specified (a typo, a spacing fix, a copy edit the user dictated). A
+product's `.claude/zeno.yaml` may tighten this under `weigh.trivial`.
+
+## Steps
+
+1. **Restate the goal** in one line — what outcome the user wants, not the
+   mechanism they named. A named mechanism ("use library X", "move to Firebase")
+   is a proposal to weigh, not a given.
+
+2. **Rules.** Run `zeno standards --constitution` for the principle titles
+   (zeno's and any the team added), and read the constitution files that
+   `zeno standards` lists — or `../../standards/constitution.md` (relative to
+   this skill) if the CLI is not installed. Note every principle the request
+   touches, by ID. Read a standard from `zeno standards` only if the request is
+   in its area.
+
+3. **Domain.** Search before you judge. Run `mcp__plugin_zeno_qmd__query` with
+   the goal in plain words, then the key nouns (product name + topic). Read the
+   top hits with `mcp__plugin_zeno_qmd__get`. Look for: an ADR that already
+   decided this, a canonical value it would change, a concept it would break.
+   If qmd is unavailable, read `.context/wiki/index.md` and `decisions/`.
+   **Architecture:** if `.claude/zeno.yaml` lists the `architecture` module, read
+   the repo's `.dependency-cruiser.cjs` and its wiki architecture concept page.
+   A request whose code would need an import a rule forbids is DO IT
+   DIFFERENTLY (name the allowed path) or PUSH BACK; one that changes a rule
+   is **too-large** unless a decision page already approves it. Cite the rule
+   by its `name`.
+
+4. **Duplicates and conflicts.** Check `.context/features/` and `.context/tasks.md`
+   of this product, and the features collections of sibling products in qmd:
+   is this already planned, built, shelved, or in progress elsewhere? Would it
+   conflict with something in `## Now`?
+
+5. **Cost vs value.**
+   - Size: **small** (1 file, < 50 lines) · **medium** (2–5 files, < 200 lines) ·
+     **large** (5+ files) · **too-large** (architecture change — split it).
+   - Ongoing cost: new dependency, new service bill, more to maintain, more to
+     test, store review risk.
+   - Value: name the user or the metric it moves (`metrics/definitions.yml` if
+     the product has one). If neither can be named, say "value unproven".
+
+6. **Write less.** Climb the ladder and stop at the first rung that works:
+   delete it → reuse something in this repo → reuse from a sibling product or
+   shared script → platform or standard library → an existing well-used package
+   → fewer lines → new code. If the `ponytail` plugin is installed, follow its
+   ladder for this step.
+
+7. **Large or too-large?** Delegate steps 2–6 to the `challenger` agent for an
+   independent read — pass it the request, the repo path and the constitution
+   and standards paths from step 2 — then reconcile: where you and it disagree,
+   show both.
+
+## Verdict
+
+Reply with exactly this block, then stop or proceed as the verdict says:
+
+```
+Verdict: DO IT | DO IT DIFFERENTLY | PUSH BACK
+Goal: <one line>
+Size: small | medium | large | too-large
+Why:
+- <C-xx> <one line> — <file or wiki page cited>
+- ...
+Instead: <only for DO IT DIFFERENTLY — the cheaper or safer way>
+Open questions: <only if a real ambiguity blocks a good answer>
+```
+
+- Every bullet under **Why** cites a principle ID and a source (a wiki page, ADR,
+  standard, feature or file). A reason with no source is an opinion — drop it or
+  mark it "unverified".
+- **DO IT** → proceed with the work in the same turn.
+- **DO IT DIFFERENTLY** → proceed with the *Instead* version only if the user
+  already accepted it; otherwise stop and ask which way.
+- **PUSH BACK** → stop. Do not start the work, not even a part of it. Ask for
+  the reason. When the user gives one, log it (below), then proceed as they say.
+
+## Logging (push back and overrides)
+
+When the user overrides a PUSH BACK or rejects a DO IT DIFFERENTLY, append one
+line to the product's log so zeno can learn from it later:
+
+```bash
+node ../../scripts/log-verdict.mjs --verdict push-back --principles C-05,C-06 \
+  --request "<one line>" --reason "<the user's reason, verbatim>"
+```
+
+(path relative to this skill). It writes to `.context/raw/zeno/verdicts.jsonl`
+in the current repo. Never edit or delete existing lines.

package/skills/wiki-lint/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: wiki-lint
+description: Audit .context/wiki/ for drift — broken [[links]], orphan pages, contradictions between entities, stale last-verified dates, unprocessed raw files. Optionally auto-fix safe issues and regenerate .context/wiki/index.md. Usage `/wiki-lint` (audit) or `/wiki-lint --fix` (audit + auto-fix).
+---
+
+You are linting the wiki at `.context/wiki/` against the wiki schema (`../../standards/wiki-schema.md`, relative to this skill).
+
+Mode: `$ARGUMENTS` (empty = audit only; `--fix` = audit + auto-fix safe issues).
+
+## Steps
+
+1. **Read the wiki schema (`../../standards/wiki-schema.md`, relative to this skill)** to refresh schema, ID conventions, required sections, and the lint-rules table.
+
+2. **Run `zeno check` first** if the CLI is installed. It checks frontmatter,
+   duplicate IDs, staleness and prices held by no entity in under a second,
+   plus any checker the repo declares. Start from its output rather than
+   re-deriving it.
+
+3. **Enumerate pages.** List every `.md` file under `.context/wiki/` (excluding `index.md` and `CLAUDE.md`). For each, parse the frontmatter.
+
+4. **Build the graph:**
+   - Map `id → file path`.
+   - For each page, extract all `[[wikilink]]` tokens from the body.
+   - Build inbound and outbound link sets per page.
+
+5. **Run the checks below.** Group findings into **Blockers** and **Warnings**.
+
+### Blockers (must be fixed)
+
+| Check | Rule |
+|---|---|
+| Missing required section | Per the wiki schema (`../../standards/wiki-schema.md`, relative to this skill) § "Page body — required sections" |
+| Broken `[[wikilink]]` | Target page does not exist |
+| Duplicate `id` | Two pages claim the same ID |
+| Contradictory canonical value | Two `entity` pages list the same key with different values |
+| `status: superseded` with no `superseded-by` | Set or remove the status |
+| Filename ↔ id slug mismatch | The filename must match the slug portion of the ID |
+| `type` does not match folder | `type: concept` must live in `concepts/`, etc. |
+
+### Warnings
+
+| Check | Rule |
+|---|---|
+| Orphan page | Zero inbound `[[wikilinks]]`. Exception: `decision` and `synthesis` pages are commonly orphan-source. |
+| Stale `last-verified` | > 90 days from today. |
+| Unprocessed raw file | A file under `.context/raw/` that no wiki page references in its `Sources`. |
+| Stale synthesis | A `synthesis` page where any `Built from` page was modified after the synthesis's `Last refresh`. |
+| Page missing two outbound links | Body has fewer than two `[[wikilinks]]`. |
+| User-facing string violates copy rules | Check quoted copy against the rules in the root `CLAUDE.md`. Best-effort. |
+
+6. **Auto-fix (only if `--fix` is in `$ARGUMENTS`):**
+   - Regenerate `.context/wiki/index.md` from scratch: enumerate pages by type, sort alphabetically by slug, keep the structure the file already has.
+   - Fix `last-verified` to today's date on any page whose body was edited in the working tree.
+   - Fix filename ↔ id slug mismatches (rename the file; do NOT change the ID).
+   - **Never** auto-fix: contradictory canonical values, missing required sections, broken `[[wikilinks]]`. These need a human decision.
+
+7. **Report.** Print:
+   - Counts: pages, blockers, warnings, auto-fixes applied.
+   - Per-finding lines: `[BLOCKER|WARN] <path>:<rule> — <detail>`.
+   - For each blocker, one suggested fix.
+   - For broken `[[wikilinks]]`, list candidate existing pages by name similarity.
+
+## Rules
+
+- **Never edit pages other than auto-fixes above.** Lint reports; the user (or `/ingest`) fixes.
+- **Never delete pages.** Superseded pages stay on disk with `status: superseded` and `superseded-by: <new-id>`.
+- **Never modify `.context/raw/`** except to warn about unprocessed files.
+- If a blocker resists auto-fix, exit non-zero (in CI mode) but always print the full report first.
+- Today's date is in the session context — use it for staleness math (>90 days).

package/standards/README.md

@@ -0,0 +1,13 @@
+# standards/
+
+zeno's default standards. `zeno standards` lists the ones that apply to a repo:
+these first, then each folder named under `standards:` in the estate's and the
+repo's `.claude/zeno.yaml`. A configured file with the same name as one of these
+replaces it; a configured `constitution.md` adds principles instead.
+
+| File | What it holds |
+|---|---|
+| `constitution.md` | The principles a request is weighed against (C-01 to C-13) |
+| `wiki-schema.md` | Wiki page types, frontmatter, required sections, lint rules |
+| `context-layout.md` | The `.context/` ten-folder layout, `features/` and `tasks.md` formats |
+| `agent-contract.md` | What every agent does before, during and after work |

package/standards/agent-contract.md

@@ -0,0 +1,40 @@
+# Agent contract
+
+What every coding agent working in a zeno repo does. A team can replace this
+file with its own `agent-contract.md` in a configured standards folder.
+
+## Before starting
+
+- Read the repo's `CLAUDE.md` / `AGENTS.md`: stack, layout, the rules that are
+  the repo's own.
+- Read `.context/tasks.md`. It is the ordered queue — the top item of `## Now`
+  is the next action. After finishing, tick the task and append a Session Note.
+- For a non-trivial request, run the weigh gate first (`/zeno:weigh`).
+
+## Repository rules
+
+1. Product material lives in whichever `.context/` folder owns it
+   (`context-layout.md`). The wiki is the knowledge base; its schema is
+   `wiki-schema.md`.
+2. Do not add top-level `docs/` or `wireframes/` folders, or root `TODO.md`,
+   `STATUS.md` or `SETUP.md`. Files a host or tool reads by exact path —
+   `README.md`, `LICENSE`, `CHANGELOG.md`, `CONTRIBUTING.md`, `SECURITY.md`,
+   `.github/` — stay at the root.
+3. Generated folders are never hand-edited; change their source and regenerate.
+
+## Comments
+
+Write a comment only to explain **why**. The code already says how.
+
+A comment earns its place when it records something the reader cannot recover
+from the code: a constraint, a trade-off, a bug it prevents, or a non-obvious
+consequence. If it restates what the next line does, delete it. No
+section-divider comments, no changelog comments, no comments restating a
+function's own name.
+
+## Before calling work done
+
+1. Reflect changed behaviour in `CLAUDE.md` and any affected `.context/` page.
+2. Run the repo's own lint, typecheck and tests.
+3. Run `zeno check`. Every checker the repo declares under `commands:` runs
+   with it.

package/standards/constitution.md

@@ -0,0 +1,89 @@
+# Constitution
+
+The principles every non-trivial request is weighed against before work starts.
+The other standards say *how* things are done; this file says what wins when a
+request and a rule disagree.
+
+Each principle has an ID that verdicts cite (`C-05`). IDs never change; a
+dropped principle is struck through, not reused. IDs C-01 to C-19 are zeno's.
+A team adds its own from C-20 up in a `constitution.md` in one of its configured
+standards folders; zeno reads both.
+
+## How a request is weighed
+
+Before acting on a non-trivial request, check it against the principles below,
+then answer with one verdict:
+
+- **Do it** — no principle is at risk.
+- **Do it differently** — the goal is fine; the way asked breaks a principle.
+  Name the principle and give the cheaper or safer way.
+- **Push back** — the request breaks a principle outright, or the cost is
+  clearly higher than the value. Stop until the owner gives a reason; log it.
+
+Every verdict cites principle IDs and the files (wiki page, ADR, standard) it
+relied on. A verdict with no citation is an opinion, not a verdict.
+
+## Principles
+
+### C-01 Shipping beats starting
+A request that finishes or unblocks something already in flight outranks one
+that starts something new. Ask: what does this move closer to a user?
+
+### C-02 One home per fact
+Every rule, value and artifact has exactly one source; everything else imports,
+links or is generated from it. A second copy is a future contradiction.
+
+### C-03 Knowledge is written down, in the repo
+A decision that lives only in chat or in one machine's memory is lost. Decisions
+become ADRs; canonical values become wiki entities; both live in git. Check the
+wiki and ADRs before answering from memory.
+
+### C-04 Decided things stay decided — until a new decision says otherwise
+A request that contradicts an ADR is not done silently. Either it follows the
+ADR, or a new ADR supersedes it, with the reason.
+
+### C-05 Value must beat cost
+Weigh effort, tokens, money and the maintenance it adds forever against who
+gains and how much. Name the user or the metric it moves; if neither can be
+named, the value is unproven.
+
+### C-06 Write less
+Before writing code: can something be deleted, reused from this repo or a
+sibling, done with the platform or standard library, or done in fewer lines?
+New code is the last rung, not the first.
+
+### C-07 Tested tools over custom ones
+Use a maintained, widely used tool before building one. Build only what no tool
+covers, and keep it small.
+
+### C-08 Products evolve together
+A fix that applies to more than one product goes into the shared standard,
+template or script — not into one product by hand. A product differs from the
+others only with a written reason.
+
+### C-09 Hard rules are code
+A rule that must never break is enforced by a linter, a check or a hook, not by
+prose. When prose keeps getting broken, turn it into a check.
+
+### C-10 Secrets are never lost and never leaked
+Every credential is backed up the moment it exists; no secret value goes into a
+commit, a Markdown file or a chat reply.
+
+### C-11 Verified, one step at a time
+Prove each step works before the next. Report failures as failures. Commit when
+asked; push only when asked.
+
+### C-12 Reversible before irreversible
+Prefer the change that can be undone. Deletes, force-pushes, store submissions,
+production deploys and permission changes are confirmed first, every time.
+
+### C-13 Users' money and data are handled exactly
+Money in integer minor units; privacy promises match what the code does; store
+claims match the app. Correctness beats speed here.
+
+## Weights
+
+A repo's `.claude/zeno.yaml` may raise or lower the weight of a principle under
+`weigh.weights` (a game might weigh C-05 higher; a finance product C-13). It may
+not remove one without a written reason, and every override shows up in
+`zeno check`.

package/standards/context-layout.md

@@ -0,0 +1,112 @@
+# The `.context/` layout
+
+Every repo keeps its non-code product material in `.context/`, in the same ten
+folders. Each has one job, and none is a bucket meaning "everything else". A team
+can replace this file with its own `context-layout.md` in a configured standards
+folder.
+
+```
+<repo>/.context/
+├── README.md        what this is, and which folders are absent and why
+├── tasks.md         the ordered queue. The top item is the next action.
+├── raw/             sources you didn't write. Immutable.
+├── wiki/            everything you concluded. Schema: wiki-schema.md
+├── features/        what's next.
+├── designs/         what it looks like.
+├── listing/         what the stores show.
+├── marketing/       how it's sold.
+├── metrics/         the numbers.
+├── support/         what you tell users.
+├── legal/           what you promise.
+└── ops/             how you run it.
+```
+
+## Rules
+
+1. **Ten folders, one job each.** There is no `documents/`, `research/`,
+   `architecture/` or `decisions/` folder: a research brief is a wiki synthesis
+   page, an architecture note is a wiki concept, an ADR is `wiki/decisions/`.
+2. **`README.md` and `tasks.md` are the only files at `.context/` root.**
+   `README.md` lists every absent folder as `n/a — <why>`.
+3. **Nothing is created empty.** A folder appears with its first file — git does
+   not track empty folders, so a placeholder disappears on clone. `raw/` is the
+   one exception and carries a `.gitkeep`.
+4. **One home per artifact; everything else is an export.** Source art lives in
+   `designs/`; store images and press kits are generated from it.
+5. **Authored vs generated is visible.** A generated file is committed but never
+   hand-edited.
+
+## What a repo is expected to have
+
+| Stage | Expected |
+|---|---|
+| any repo | `README.md` · `tasks.md` |
+| uses the `docs` or `knowledge` module | + `raw/` · `wiki/` · `features/` |
+| draws its UI | + `designs/` (optional; an estate can require it with a command) |
+| has a store presence | + `listing/` |
+| is live to users | + `marketing/` · `metrics/` · `support/` · `legal/` |
+| once something runs | + `ops/` |
+
+## Naming and frontmatter
+
+- Append-only, time-ordered files → ISO date: `YYYY-MM-DD-slug.md`.
+- Files referenced by a stable ID → zero-padded number: `NNNN-slug.md`.
+- Frontmatter follows the wiki schema: `id`, `type`, `status`, `last-verified`,
+  `supersedes`, `superseded-by`. Kebab-case keys.
+
+## `features/` — what is next
+
+One page per feature, `NNNN-<slug>.md`:
+
+```markdown
+---
+id: FEAT-0031
+type: feature             # feature | experiment | chore | platform
+status: building          # planned | building | shipped | shelved | superseded
+last-verified: 2026-04-02
+release: 3.4.0
+---
+## Summary · ## Motivation · ## Acceptance scenarios (Given/When/Then)
+## Out of scope · ## Open questions
+## Store copy
+> One or two sentences users will read in the release notes.
+```
+
+The wiki describes what *is*; `features/` describes what is *next*. A shipped
+feature goes `status: shipped` and is never deleted.
+
+## `tasks.md` — the ordered queue
+
+```markdown
+---
+updated: 2026-09-29
+horizon: 2026-10-13        # this file is stale after this date
+---
+
+# Tasks
+
+## Now                       <!-- position is the dependency; do in order -->
+1. [ ] T001 Add a screenshot mode  `feat:0002`  ~1d
+2. [ ] T002 Write the capture flows  needs:T001  ~3h
+
+## Parallel                  <!-- independent, safe to batch -->
+- [ ] T004 [P] Move the SKU IDs into the wiki  ~1h
+
+## Blocked
+- [ ] T005 Submit the iOS build
+      blocked-by: store account access  since:2026-09-16
+      unblock: ask for the role  next-check:2026-10-06
+
+## Waiting                   <!-- deferred by time, not by a task -->
+- [ ] T006 Second-language listing  wait:2026-11-01
+
+## Done
+- [x] T000 Set up .context  done:2026-09-29
+
+## Session Notes
+### 2026-09-29
+- Done: T000.  Learned: …  Next: T001.
+```
+
+A blocker with no named unblocking action and no check date is a silent leak.
+A task that needs more than a line and a continuation is a `features/` page.