@freetesh/zeno 0.9.1 → 0.11.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "zeno",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "description": "Keeps your domain knowledge and AI rules local and enforces them, so Claude hallucinates less.",
   "author": {
     "name": "Ritesh Firodiya",

package/README.md

@@ -36,7 +36,8 @@ It has two halves that read the same config:
   constitution, your wiki and decision records, existing features and tasks,
   cost vs value, and the write-less ladder, then answers **DO IT**, **DO IT
   DIFFERENTLY** or **PUSH BACK** with citations. Push back stops work until you
-  give a reason; overrides are logged and feed `zeno learn`.
+  give a reason. Every verdict is logged; `zeno learn` shows how often the gate
+  stops you and turns repeated overrides into proposals.
 - **No assumptions.** A request is not a fact. Each claim in it ("users want
   this", "it is slow") is checked against the repo and its data sources and
   marked backed or not. Work that rests on an assumption stops until you agree
@@ -53,8 +54,17 @@ It has two halves that read the same config:
   `.context` layout, agent contract). A team adds or replaces them from its own
   folder; a repo can override again. `zeno standards` shows what applies.
 - **Hard rules are checks.** `zeno check` validates layout, wiki frontmatter,
-  stale pages, prices with no canonical home, copied standards, and runs every
-  checker your config declares.
+  stale pages, placeholder text, page and `tasks.md` size caps, prices with no
+  canonical home, copied standards, and runs every checker your config declares.
+- **Context stays small.** A line belongs in `.context/` only if an agent would
+  get something wrong without it. Decisions are one file per topic, overwritten
+  when the choice changes; `tasks.md` holds open work only; history is git's.
+- **Stages stop at their gates.** A `pipeline:` in `zeno.yaml` lists your
+  stages in order, with the paths that show each has started. A gated stage
+  needs a person to run `zeno approve <stage>` before any later stage starts;
+  `zeno check` fails otherwise. Approvals are dated in
+  `.context/raw/zeno/gates.jsonl`, so you can see where work waits. A product
+  replaces the estate's pipeline by declaring its own.
 - **Each repo's architecture is enforced.** With the `architecture` module, a
   repo keeps its own import rules in `.dependency-cruiser.cjs` files: one at the
   root, or one per workspace under `apps/` and `packages/` (each runs from its
@@ -140,7 +150,7 @@ doctor:
   tools:
     - { tool: pnpm, why: product scripts, hint: npm i -g pnpm }
 wiki:
-  types:                            # added to the six built-in page types
+  types:                            # added to the built-in folders (concepts, entities, decisions, surfaces, synthesis)
     - type: postmortem
       folder: postmortems
       reason: incidents need a timeline and a fix
@@ -152,7 +162,7 @@ context:
 
 ```yaml
 # <repo>/.claude/zeno.yaml — written by `zeno init`
-zeno: 0.9.0
+zeno: 0.11.0
 kind: expo-app                      # expo-app | web | content
 modules: [docs, knowledge, code, listing]   # all optional; design is added when .context/designs exists, metrics only when asked
 packs: [expo]
@@ -172,8 +182,8 @@ carry a `reason:`, and `zeno check` lists every override.
 | zeno default | What it holds |
 |---|---|
 | `constitution.md` | Principles C-01–C-15 a request is weighed against. A team adds C-20+ in its own `constitution.md`. |
-| `wiki-schema.md` | Wiki page types, frontmatter, required sections, lint rules |
-| `context-layout.md` | The `.context/` ten-folder layout, `features/` and `tasks.md` |
+| `wiki-schema.md` | What belongs in the wiki, its folders, decisions, frontmatter and size caps |
+| `context-layout.md` | The `.context/` ten-folder layout, `features/` and `tasks.md` (open work only) |
 | `agent-contract.md` | What every agent does before, during and after work |
 
 ## Packs
@@ -202,7 +212,7 @@ hooks/            session start: constitution titles, qmd refresh
 standards/        default standards
 packs/            vendor doc packs
 templates/        files init writes: dependency-cruiser base (synced) and starters
-scripts/          log-verdict.mjs — append-only override log
+scripts/          log-verdict.mjs — append-only verdict log
 cli/              the zeno CLI (TypeScript, vitest; built to cli/dist for npm)
 evals/            plugin evals and the fixture product
 ```

package/cli/dist/checks/canonical-values.js

@@ -10,25 +10,27 @@ const PRICE_WORDS = /pric|cost|paywall|plan|tier|subscri|bundle|pack|purchase|bu
 function amounts(text) {
     return (text.match(PRICE) ?? []).map((price) => price.replace(/\s/g, ""));
 }
+// A decision's `Rejected:` line names old prices on purpose; they are history, not a second home.
+const REJECTED = /^\*\*Rejected:\*\*/;
 function pricesIn(text) {
-    const paragraphs = text.replace(CODE_BLOCK, "").split(/\n\s*\n/);
+    const paragraphs = text.replace(CODE_BLOCK, "").split(/\n\s*\n/).filter((paragraph) => !REJECTED.test(paragraph.trim()));
     return [...new Set(paragraphs.filter((paragraph) => PRICE_WORDS.test(paragraph)).flatMap(amounts))];
 }
 function heldAmounts(text) {
     return amounts(text.replace(CODE_BLOCK, ""));
 }
+const folderOf = (file) => file.split("/")[2];
 export const canonicalValues = {
     id: "canonical-values",
     module: "docs",
-    description: "a price shown on a surface page is held by an entity page — one home per fact (C-04)",
+    description: "a price stated in a decision or screen note is held by an entity page — one home per fact (C-02)",
     run({ repo }) {
         const pages = wikiPages(repo).map((file) => ({ file, ...parseFrontmatter(readFileSync(join(repo, file), "utf8")) }));
-        const live = pages.filter((page) => page.data?.status !== "superseded");
-        const held = new Set(live.filter((page) => page.data?.type === "entity").flatMap((page) => heldAmounts(page.body)));
-        // Surfaces are where store prices get restated. Concepts legitimately carry
+        const held = new Set(pages.filter((page) => folderOf(page.file) === "entities").flatMap((page) => heldAmounts(page.body)));
+        // Decisions and screen notes are where prices get restated. Concepts legitimately carry
         // example amounts (a tax product explains slabs with them).
-        return live
-            .filter((page) => page.data?.type === "surface")
+        return pages
+            .filter((page) => ["decisions", "surfaces"].includes(folderOf(page.file)))
             .flatMap((page) => {
             const orphans = pricesIn(page.body).filter((price) => !held.has(price));
             if (orphans.length === 0)

package/cli/dist/checks/context-size.js

@@ -0,0 +1,46 @@
+import { existsSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { REMOVED_WIKI_FOLDERS as REMOVED_FOLDERS } from "../config/schema.js";
+import { wikiPages } from "./wiki-frontmatter.js";
+// Every line here is read by an agent on every task; a cap keeps .context to what it would get wrong without.
+const MAX_LINES = { page: 60, decision: 30, readme: 30, tasks: 100 };
+const DATED_NAME = /^\d{4}-\d{2}-\d{2}-/;
+const lineCount = (repo, file) => readFileSync(join(repo, file), "utf8").trimEnd().split("\n").length;
+export const contextSize = {
+    id: "context-size",
+    module: "docs",
+    description: "pages, decisions, README.md and tasks.md stay under their line caps; decisions are one file per topic; no flow pages",
+    run({ repo }) {
+        const findings = [];
+        const warn = (file, message) => findings.push({ check: "context-size", level: "warn", file, message });
+        const overCap = (file, cap) => {
+            const lines = lineCount(repo, file);
+            if (lines > cap)
+                warn(file, `${lines} lines, cap ${cap} — cut what code, designs or git already say`);
+        };
+        for (const [folder, why] of Object.entries(REMOVED_FOLDERS)) {
+            if (existsSync(join(repo, ".context/wiki", folder)))
+                warn(`.context/wiki/${folder}`, `${folder}/ is gone: ${why}`);
+        }
+        for (const file of wikiPages(repo)) {
+            const folder = file.split("/")[2];
+            if (folder === "synthesis" || folder in REMOVED_FOLDERS)
+                continue;
+            if (folder === "decisions" && DATED_NAME.test(basename(file))) {
+                warn(file, "name a decision by topic and edit it in place — git keeps the history");
+            }
+            overCap(file, folder === "decisions" ? MAX_LINES.decision : MAX_LINES.page);
+        }
+        const readme = ".context/README.md";
+        const tasks = ".context/tasks.md";
+        if (existsSync(join(repo, readme)))
+            overCap(readme, MAX_LINES.readme);
+        if (existsSync(join(repo, tasks))) {
+            overCap(tasks, MAX_LINES.tasks);
+            if (/^## (Done|Session Notes)\b/m.test(readFileSync(join(repo, tasks), "utf8"))) {
+                warn(tasks, "tasks.md holds only open work — delete done tasks and session notes; the commits record them");
+            }
+        }
+        return findings;
+    },
+};

package/cli/dist/checks/index.js

@@ -1,19 +1,23 @@
 import { architecture } from "./architecture.js";
 import { canonicalValues } from "./canonical-values.js";
 import { contextLayout } from "./context-layout.js";
+import { contextSize } from "./context-size.js";
 import { staleCopies, standardsCopies } from "./copies.js";
 import { commandChecks } from "./external.js";
 import { metricsDefinitions } from "./metrics.js";
+import { pipeline } from "./pipeline.js";
 import { sources } from "./sources.js";
 import { wikiFrontmatter } from "./wiki-frontmatter.js";
 export const ALL_CHECKS = [
     contextLayout,
     wikiFrontmatter,
+    contextSize,
     canonicalValues,
     standardsCopies,
     staleCopies,
     architecture,
     metricsDefinitions,
     sources,
+    pipeline,
     commandChecks,
 ];

package/cli/dist/checks/pipeline.js

@@ -0,0 +1,34 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { readApprovals } from "../pipeline.js";
+/**
+ * Stages run in the order zeno.yaml lists them. A stage has started once one
+ * of its `done` paths exists; a gated stage must be approved before any later
+ * stage starts. Each unapproved gate is reported once, at the first later
+ * stage that started.
+ */
+export const pipeline = {
+    id: "pipeline",
+    module: null,
+    description: "no stage starts before every earlier gate is approved",
+    run({ repo, config }) {
+        const approved = new Set(readApprovals(repo).map((approval) => approval.stage));
+        const startedAt = config.pipeline.map((stage) => stage.done.find((path) => existsSync(join(repo, path))));
+        return config.pipeline.flatMap((gate, index) => {
+            if (!gate.gate || approved.has(gate.id))
+                return [];
+            const later = config.pipeline.findIndex((_, i) => i > index && startedAt[i] !== undefined);
+            if (later === -1)
+                return [];
+            const stage = config.pipeline[later];
+            return [
+                {
+                    check: "pipeline",
+                    level: "error",
+                    file: startedAt[later],
+                    message: `stage "${stage.id}" started before gate "${gate.id}" was approved — review ${gate.id}, then a person runs \`zeno approve ${gate.id}\``,
+                },
+            ];
+        });
+    },
+};

package/cli/dist/checks/wiki-frontmatter.js

@@ -2,8 +2,11 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { listFiles } from "../lib/files.js";
 import { parseFrontmatter } from "../lib/frontmatter.js";
-import { WIKI_FOLDER_BY_TYPE } from "../config/schema.js";
-const REQUIRED_FIELDS = ["id", "type", "status", "last-verified"];
+import { REMOVED_WIKI_FOLDERS, WIKI_FOLDER_BY_TYPE } from "../config/schema.js";
+const REQUIRED_FIELDS = ["last-verified"];
+// Filler an agent would read as fact: a section with nothing to say is deleted, not stubbed.
+const PLACEHOLDER = /\bTBD\b|\bnone yet\b|\bpopulate when\b/i;
+const CODE_BLOCK = /```[\s\S]*?```/g;
 const STALE_AFTER_DAYS = 90;
 const DAY_MS = 86_400_000;
 const NOT_PAGES = ["index.md", "CLAUDE.md"];
@@ -18,7 +21,7 @@ function asDate(value) {
 export const wikiFrontmatter = {
     id: "wiki-frontmatter",
     module: "docs",
-    description: "every wiki page has id, type, status and last-verified; type matches folder; ids are unique; nothing stale",
+    description: "every wiki page has last-verified and no placeholder text; a type, if set, matches its folder; ids are unique; nothing stale",
     run({ repo, config, today }) {
         const folderByType = { ...WIKI_FOLDER_BY_TYPE, ...Object.fromEntries(config.wiki.types.map((entry) => [entry.type, entry.folder])) };
         // Built-in types' sections are linted by the wiki-lint skill; added types carry theirs in config.
@@ -28,6 +31,9 @@ export const wikiFrontmatter = {
         const filesById = new Map();
         const stale = [];
         for (const file of wikiPages(repo)) {
+            const folder = file.split("/")[2];
+            if (folder in REMOVED_WIKI_FOLDERS)
+                continue; // context-size reports the folder once
             const { data, body } = parseFrontmatter(readFileSync(join(repo, file), "utf8"));
             if (!data) {
                 add("error", file, "no frontmatter");
@@ -36,10 +42,11 @@ export const wikiFrontmatter = {
             const missing = REQUIRED_FIELDS.filter((field) => data[field] === undefined || data[field] === null);
             if (missing.length > 0)
                 add("error", file, `missing ${missing.join(", ")}`);
-            const folder = file.split("/")[2];
             const expected = folderByType[String(data.type)];
             if (data.type && expected !== folder)
                 add("error", file, `type ${data.type} does not belong in ${folder}/`);
+            if (!data.type && !Object.values(folderByType).includes(folder))
+                add("error", file, `${folder}/ is not a wiki folder`);
             const sections = sectionsByType.get(String(data.type));
             if (sections) {
                 const headings = new Set(body.split("\n").flatMap((line) => (line.startsWith("## ") ? [line.slice(3).trim()] : [])));
@@ -47,8 +54,9 @@ export const wikiFrontmatter = {
                 if (absent.length > 0)
                     add("error", file, `missing sections: ${absent.join(", ")}`);
             }
-            if (data.status === "superseded" && !data["superseded-by"])
-                add("error", file, "superseded without superseded-by");
+            const placeholder = body.replace(CODE_BLOCK, "").match(PLACEHOLDER);
+            if (placeholder)
+                add("warn", file, `placeholder "${placeholder[0]}" — write the fact or delete the section`);
             const verified = asDate(data["last-verified"]);
             const age = verified ? Math.floor((today.getTime() - verified.getTime()) / DAY_MS) : 0;
             if (verified && age > STALE_AFTER_DAYS)

package/cli/dist/commands/approve.js

@@ -0,0 +1,20 @@
+import { resolve } from "node:path";
+import { loadConfig } from "../config/load.js";
+import { recordApproval } from "../pipeline.js";
+export function registerApprove(program) {
+    program
+        .command("approve")
+        .description("record that a person reviewed and approved a pipeline gate, dated now (a person runs this, not an agent)")
+        .argument("<stage>", "the gated stage's id in zeno.yaml `pipeline:`")
+        .argument("[repo]", "product repo", ".")
+        .option("--note <text>", "what was reviewed", "")
+        .action((stageId, repo, options) => {
+        const root = resolve(repo);
+        const gates = loadConfig(root).config.pipeline.filter((stage) => stage.gate).map((stage) => stage.id);
+        if (!gates.includes(stageId)) {
+            throw new Error(`"${stageId}" is not a gated stage here — gates: ${gates.join(", ") || "none (no pipeline: in zeno.yaml)"}`);
+        }
+        const approval = recordApproval(root, stageId, options.note);
+        console.log(`approved ${stageId} at ${approval.at}`);
+    });
+}

package/cli/dist/commands/learn.js

@@ -1,11 +1,11 @@
-import { proposals, readDecisions, readVerdicts, recordDecision } from "../learn.js";
+import { proposals, readDecisions, readVerdicts, recordDecision, summarise } from "../learn.js";
 import { findProducts } from "../run.js";
 import { requireEstate } from "./env.js";
 const DEFAULT_THRESHOLD = 3;
 export function registerLearn(program, env) {
     program
         .command("learn")
-        .description("turn overridden verdicts across products into proposals to change the rules")
+        .description("show how often the gate stops work, and turn overrides across products into proposals to change the rules")
         .option("--threshold <n>", "overrides of one principle before it is proposed", String(DEFAULT_THRESHOLD))
         .option("--approve <id>", "mark a proposal approved (then edit the standard)")
         .option("--reject <id>", "mark a proposal rejected; it returns only with new evidence")
@@ -23,7 +23,8 @@ export function registerLearn(program, env) {
             console.log(`${options.approve ? "approved" : "rejected"} ${target}`);
             return;
         }
-        console.log(`${entries.length} overridden verdict(s) logged across the estate`);
+        const s = summarise(entries);
+        console.log(`${s.total} verdict(s) logged: ${s.proceeded} went ahead, ${s.stopped} stopped, ${s.overridden} overridden, ${s.dropped} dropped`);
         if (found.length === 0)
             console.log("no proposals");
         for (const proposal of found) {

package/cli/dist/config/load.js

@@ -89,6 +89,7 @@ export function loadConfig(repo, options = {}) {
         weigh: { weights: Object.assign({}, ...pick("weigh").map((weigh) => weigh?.weights)) },
         wiki: { types: mergeBy(pick("wiki").map((wiki) => wiki?.types ?? []), (entry) => entry.type) },
         context: { folders: mergeBy(pick("context").map((context) => context?.folders ?? []), (entry) => entry.folder) },
+        pipeline: lastDefined(pick("pipeline")) ?? [],
     };
     if (Object.keys(config.expo ?? {}).length === 0)
         delete config.expo;

package/cli/dist/config/schema.js

@@ -1,15 +1,21 @@
 import { z } from "zod";
 export const KINDS = ["expo-app", "web", "content"];
 export const MODULES = ["docs", "design", "knowledge", "metrics", "code", "architecture", "listing"];
-/** The wiki page types every repo has, and the folder each lives in. A repo adds more under `wiki.types`. */
+/**
+ * The wiki page types every repo has, and the folder each lives in. A repo adds more under `wiki.types`.
+ * No flow type: a journey worth keeping is a concept. A surface page is a screen's notes, only where it has real ones.
+ */
 export const WIKI_FOLDER_BY_TYPE = {
     concept: "concepts",
     entity: "entities",
     surface: "surfaces",
-    flow: "flows",
     decision: "decisions",
     synthesis: "synthesis",
 };
+/** Wiki folders that no longer exist, and what to do with what was in them. */
+export const REMOVED_WIKI_FOLDERS = {
+    flows: "fold a journey worth keeping into a concept page",
+};
 /** The `.context/` folders every repo may have. A repo adds more under `context.folders`. */
 export const CONTEXT_FOLDERS = ["raw", "wiki", "features", "designs", "listing", "marketing", "metrics", "support", "legal", "ops"];
 const checkOverride = z
@@ -43,6 +49,15 @@ const wikiType = z
     message: "a built-in wiki type or its folder cannot be redefined — add a new one",
 });
 const contextFolder = z.object({ folder: kebab, reason }).strict();
+const stage = z
+    .object({
+    id: kebab,
+    /** Paths that exist once the stage has started; any one is enough. */
+    done: z.array(z.string().min(1)).min(1),
+    /** A person must approve this stage (`zeno approve <id>`) before any later stage starts. */
+    gate: z.boolean().default(false),
+})
+    .strict();
 const tool = z.object({ tool: z.string(), why: z.string(), hint: z.string() }).strict();
 /** One layer of `.claude/zeno.yaml` as written: every field optional. */
 export const layerSchema = z
@@ -62,6 +77,8 @@ export const layerSchema = z
     weigh: z.object({ weights: z.record(principleId, z.number().nonnegative()) }).partial(),
     wiki: z.object({ types: z.array(wikiType) }).partial(),
     context: z.object({ folders: z.array(contextFolder) }).partial(),
+    /** The stages work goes through, in order. A more specific layer replaces the whole list. */
+    pipeline: z.array(stage),
 })
     .partial()
     .strict();

package/cli/dist/index.js

@@ -2,6 +2,7 @@
 import { resolve } from "node:path";
 import { Command } from "commander";
 import { registerAdd } from "./commands/add.js";
+import { registerApprove } from "./commands/approve.js";
 import { registerCheck } from "./commands/check.js";
 import { registerDoctor } from "./commands/doctor.js";
 import { registerInit } from "./commands/init.js";
@@ -29,6 +30,7 @@ registerStandards(program, env);
 registerDoctor(program);
 registerUi(program, env);
 registerLearn(program, env);
+registerApprove(program);
 registerWeigh(program);
 program.parseAsync().catch((error) => {
     console.error(`zeno: ${error.message}`);

package/cli/dist/init.js

@@ -66,12 +66,12 @@ const FIRST_FILE = {
     wiki: ".context/wiki/index.md",
     features: ".context/features/index.md",
 };
-function template(file, today) {
+function template(file) {
     switch (file) {
         case ".context/README.md":
             return "# .context\n\nProduct material, in the ten folders of the zeno context layout.\n\n## Absent folders\n\n- listing/ — n/a — no store presence yet\n- marketing/, metrics/, support/, legal/ — n/a — not live yet\n- ops/ — n/a — nothing to run yet\n";
         case ".context/tasks.md":
-            return `---\nupdated: ${today}\nhorizon: ${today}\n---\n\n# Tasks\n\n## Now\n\n## Parallel\n\n## Blocked\n\n## Waiting\n\n## Done\n\n## Session Notes\n`;
+            return "# Tasks\n\n## Now\n\n## Blocked\n\n## Waiting\n";
         case ".context/wiki/index.md":
             return "# Wiki index\n\nPages by type. Schema: the zeno plugin's wiki-schema standard.\n";
         case ".context/features/index.md":
@@ -98,7 +98,6 @@ export function planInit(repo, answers) {
     return { config, create };
 }
 export function applyInit(repo, plan, options) {
-    const today = options.today ?? new Date().toISOString().slice(0, 10);
     const write = (file, content) => {
         mkdirSync(dirname(join(repo, file)), { recursive: true });
         writeFileSync(join(repo, file), content);
@@ -107,7 +106,7 @@ export function applyInit(repo, plan, options) {
     const starters = new Map(architectureStarters(repo).map((s) => [s.file, s.template]));
     for (const file of plan.create) {
         const starter = starters.get(file);
-        write(file, starter ? readFileSync(join(options.zenoRoot, ARCHITECTURE_TEMPLATES, starter), "utf8") : template(file, today));
+        write(file, starter ? readFileSync(join(options.zenoRoot, ARCHITECTURE_TEMPLATES, starter), "utf8") : template(file));
     }
     if (plan.config.modules.includes("knowledge"))
         indexKnowledge(repo, options.name, options.run);

package/cli/dist/learn.js

@@ -1,5 +1,14 @@
 import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { basename, join } from "node:path";
+export const OUTCOMES = ["proceeded", "stopped", "overridden", "dropped"];
+const outcomeOf = (entry) => entry.outcome ?? "overridden";
+/** How often the gate let work through, stopped it, or was overridden. */
+export function summarise(entries) {
+    const counts = Object.fromEntries(OUTCOMES.map((o) => [o, 0]));
+    for (const entry of entries)
+        counts[outcomeOf(entry)] += 1;
+    return { total: entries.length, ...counts };
+}
 const LOG = join(".context", "raw", "zeno", "verdicts.jsonl");
 const MAX_REASONS = 5;
 function readJsonLines(path) {
@@ -41,7 +50,9 @@ function toProposal(id, summary, entries) {
  * times, or one reason given in two or more products. A decided proposal comes
  * back only when its count has grown past what it was when decided.
  */
-export function proposals(entries, options) {
+export function proposals(all, options) {
+    // Only an override says a rule may be wrong; a verdict the user followed says nothing about it.
+    const entries = all.filter((entry) => outcomeOf(entry) === "overridden");
     const found = [];
     for (const [principle, group_] of group(entries, (e) => e.principles)) {
         if (group_.length >= options.threshold) {

package/cli/dist/pipeline.js

@@ -0,0 +1,20 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+// In raw/, which is append-only: the dates are the record of how long each stage waited.
+export const GATES_LOG = join(".context", "raw", "zeno", "gates.jsonl");
+export function readApprovals(repo) {
+    const path = join(repo, GATES_LOG);
+    if (!existsSync(path))
+        return [];
+    return readFileSync(path, "utf8")
+        .split("\n")
+        .filter((line) => line.trim())
+        .map((line) => JSON.parse(line));
+}
+export function recordApproval(repo, stage, note) {
+    const approval = { stage, at: new Date().toISOString(), note };
+    const path = join(repo, GATES_LOG);
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(path, `${JSON.stringify(approval)}\n`);
+    return approval;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@freetesh/zeno",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "description": "zeno CLI: keep your domain knowledge and AI rules in your repo, and enforce them.",
   "license": "MIT",
   "author": "Ritesh Firodiya",

package/skills/ask/SKILL.md

@@ -15,9 +15,8 @@ Question: `$ARGUMENTS`
    - `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"
+   - `decision` pages for "why did we choose X over Y", and its `Rejected:` line for "did we consider Y"
+   - for "what does this screen do", the HTML in `.context/designs/` is the spec; its `surfaces/` note, if any, says why
 
 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.
 
@@ -35,8 +34,7 @@ Question: `$ARGUMENTS`
 
 ## Rules
 
-- **Never read `.context/raw/` or `.context/designs/` from this skill.** If the answer requires raw inspection, refuse and recommend `/ingest`.
+- **Never read `.context/raw/` from this skill.** If the answer requires raw inspection, recommend `/ingest`. Designs may be read for screen questions.
 - **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

@@ -1,33 +1,36 @@
 ---
 name: decision
-description: Record a product or technical decision as a new ADR page in .context/wiki/decisions/. Usage `/decision <title> — <body>`.
+description: Record or change a product or technical decision in .context/wiki/decisions/<topic>.md — one file per topic, overwritten when the choice changes. Usage `/decision <topic> — <choice and why>`.
 ---
 
-You are logging a decision as a new `.context/wiki/decisions/<YYYY-MM-DD>-<slug>.md` page.
+You are recording a decision in `.context/wiki/decisions/<topic>.md`.
 
-Decision to record: `$ARGUMENTS`
+Decision: `$ARGUMENTS`
 
 ## Steps
 
-1. Get the shape. If `.context/wiki/decisions/` already holds pages, open the most recent one and match its frontmatter and sections — that is enough. Only when there is none, read two parts of the wiki schema (the `wiki-schema.md` that `zeno standards` lists — a team's own replaces zeno's; without the CLI, `../../standards/wiki-schema.md` relative to this skill): § "Frontmatter" and § "`decision`". Find their line numbers with Grep and Read just those ranges, not the whole file.
-
-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>`.
+1. Split `$ARGUMENTS` on the first ` — `: left = topic, right = the choice and why. With no ` — `, ask for the choice.
+2. Slug = the topic in kebab-case, no date (`pricing`, `auth-provider`). Look for an existing file on the same topic first, under any name. If there is one, it is the file to change.
+3. Write the file, at most 30 lines:
+
+   ```markdown
+   ---
+   last-verified: <today>
+   ---
+   # <Topic>
+   **Choice:** <one or two lines; link values to their entity page>
+   **Why:** <the trigger: data, incident, user feedback, cost>
+   **Rejected:** <option (why)> · <option (why)>
+   ```
+
+   When changing an existing decision, replace the choice and why, and move the
+   old choice into `Rejected:` with the reason it was dropped. Keep the rest of `Rejected:`.
+4. Put a price, SKU or limit on its entity page, not here (`canonical-values` checks this).
+5. Add or update the one line in `.context/wiki/index.md`.
+6. Confirm: `decision recorded: <topic> → <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.
+- One file per topic, overwritten. Git keeps the old text; never add a dated or `-2` file.
+- No fix lists, audit results or step-by-step history. Those go in the commit message or `CHANGELOG.md`.
+- If the user's text is long, keep the choice, the reason and what was rejected, and drop the rest. Show what you dropped.

package/skills/ingest/SKILL.md

@@ -9,28 +9,27 @@ Source to ingest: `$ARGUMENTS`
 
 ## Steps
 
-1. **Read the wiki schema (the `wiki-schema.md` that `zeno standards` lists — a team's own replaces zeno's; without the CLI, `../../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.
+1. **Read the wiki schema (the `wiki-schema.md` that `zeno standards` lists — a team's own replaces zeno's; without the CLI, `../../standards/wiki-schema.md` relative to this skill) first.** It defines the folders, the one test for what belongs, and the caps. 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
+   - HTML wireframe → nothing; the HTML is the spec. Only a constraint it can't show becomes that screen's `surfaces/<slug>.md` note.
+   - Decision note → the `decisions/<topic>.md` file, via the `decision` skill's format
    - 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
+   - A user journey description → a concept, only if it holds a rule the designs don't show
+   - Write nothing an agent could read from the code, the designs or git.
    - Don't force one source into one page — a meeting note can produce multiple pages.
-   - Page types are the six in the schema plus any listed under `wiki.types` in the repo's or the estate's `.claude/zeno.yaml`, each with its folder and its required `sections` (use exactly those `## ` headings, in that order; its ID is `<TYPE>.<SLUG>`). Use an added type only when the source fits it.
+   - Folders are the four in the schema plus any listed under `wiki.types` in the repo's or the estate's `.claude/zeno.yaml`, each with its folder and its required `sections` (use its `sections` headings). Use an added type only when the source fits it.
 
 4. **For each page you will create:**
-   - Pick the ID per the wiki schema § "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. 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.
+   - Filename: the topic, lowercase kebab-case, no date.
+   - Check whether a page on the topic already exists. If yes, edit it in place and refresh `last-verified` to today. Keep any `id`.
+   - Write only sections with something to say. No placeholders. Stay under the caps (page 60 lines).
+   - Link related pages with `[[slug]]` where it helps a reader. List the source path under `Sources`.
 
-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.
+5. **Update `.context/wiki/index.md`:** one line for the new page, under its folder heading, alphabetical. 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.
 
@@ -39,7 +38,7 @@ Source to ingest: `$ARGUMENTS`
 ## 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 delete or rename an existing wiki page from this skill.
 - 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/weigh/SKILL.md

@@ -134,17 +134,27 @@ Proceed only after the user agrees in writing ("agree", or "agree to 1–4").
 "Go ahead" to a verdict is not agreement to terms that were never shown. Work
 covers only the terms agreed to.
 
-## Logging (push back and overrides)
+## Logging (every verdict)
 
-When the user overrides a PUSH BACK, rejects a DO IT DIFFERENTLY or agrees to
-terms, append one line to the product's log so zeno can learn from it later.
-Pass each agreed term with its own `--term`:
+Log every verdict once, when you know what happened next. A trivial request
+that skipped the gate is not logged. `--outcome` is one of:
+
+- `proceeded` — work went ahead as the verdict said (DO IT, or an accepted
+  *Instead*).
+- `stopped` — you stopped and asked, and the user has not answered yet. Log it
+  when you stop; if the user later overrides, log a second line.
+- `overridden` — the user went on against a PUSH BACK, rejected a DO IT
+  DIFFERENTLY, or agreed to terms. `--reason` is required: the user's reason,
+  verbatim. Pass each agreed term with its own `--term`.
+- `dropped` — the user chose to drop the request.
 
 ```bash
-node ../../scripts/log-verdict.mjs --verdict push-back --principles C-04,C-14 \
-  --request "<one line>" --reason "<the user's reason, verbatim>" \
-  --term "<term 1>" --term "<term 2>"
+node ../../scripts/log-verdict.mjs --verdict push-back --outcome overridden \
+  --principles C-04,C-14 --request "<one line>" \
+  --reason "<the user's reason, verbatim>" --term "<term 1>" --term "<term 2>"
 ```
 
 (path relative to this skill). It writes to `.context/raw/zeno/verdicts.jsonl`
-in the current repo. Never edit or delete existing lines.
+in the current repo. Never edit or delete existing lines. `zeno learn` reads
+the log across products: how often the gate stops work, and which rules keep
+being overridden.

package/skills/wiki-lint/SKILL.md

@@ -9,10 +9,11 @@ Mode: `$ARGUMENTS` (empty = audit only; `--fix` = audit + auto-fix safe issues).
 
 ## Steps
 
-1. **Read the wiki schema** to refresh schema, ID conventions, required sections, and the lint-rules table.
+1. **Read the wiki schema** to refresh the folders, the one test and the caps.
 
 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,
+   placeholders, caps, dated decision names, 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.
 
@@ -29,30 +30,27 @@ Mode: `$ARGUMENTS` (empty = audit only; `--fix` = audit + auto-fix safe issues).
 
 | Check | Rule |
 |---|---|
-| Missing required section | Per the wiki schema § "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. A type added under `wiki.types` in `.claude/zeno.yaml` lives in its configured folder and has every heading in its `sections`. |
+| Placeholder text | `TBD`, `none yet`: write the fact or delete the section |
+| `type` does not match folder | If a page sets `type`, it lives in that type's folder |
 
 ### Warnings
 
 | Check | Rule |
 |---|---|
-| Orphan page | Zero inbound `[[wikilinks]]`. Exception: `decision` and `synthesis` pages are commonly orphan-source. |
+| Over a cap | Page 60 lines, decision 30, README 30, tasks 100 |
+| Restates code, a design or git | Delete the lines; link the source instead |
+| Two pages on one topic | Merge into one, edited in place |
 | 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.
+   - **Never** auto-fix: contradictory canonical values, broken `[[wikilinks]]`, merges or cuts. These need a human decision.
 
 7. **Report.** Print:
    - Counts: pages, blockers, warnings, auto-fixes applied.
@@ -63,7 +61,7 @@ Mode: `$ARGUMENTS` (empty = audit only; `--fix` = audit + auto-fix safe issues).
 ## 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 delete pages from this skill.** Propose the cut; the user approves it. Git keeps what is deleted.
 - **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/agent-contract.md

@@ -8,7 +8,7 @@ file with its own `agent-contract.md` in a configured standards folder.
 - 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.
+  is the next action. After finishing, delete the task.
 - For a non-trivial request, run the weigh gate first (`/zeno:weigh`).
 
 ## Repository rules
@@ -40,7 +40,8 @@ function's own name.
 
 ## Before calling work done
 
-1. Reflect changed behaviour in `CLAUDE.md` and any affected `.context/` page.
+1. Update any `.context/` page the change made wrong. Add a page only if an
+   agent would get something wrong without it.
 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/context-layout.md

@@ -52,10 +52,10 @@ folder.
 
 ## 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.
+- Dated sources (`raw/`) → ISO date: `YYYY-MM-DD-slug.md`.
+- Features → zero-padded number: `NNNN-slug.md`.
+- Everything else is named by topic and edited in place.
+- Frontmatter: `last-verified`, kebab-case keys. See the wiki schema.
 
 ## Where each kind of document lives
 
@@ -64,8 +64,8 @@ separate folder per name.
 
 | Document | Home |
 |---|---|
-| ADR | `wiki/decisions/`, `status: canonical` |
-| RFC | `wiki/decisions/`, `status: draft` — the same page becomes the ADR when accepted |
+| ADR | `wiki/decisions/<topic>.md`, overwritten when the choice changes |
+| RFC | `features/`; once accepted, the choice goes in `wiki/decisions/` |
 | PRD | `features/`, `type: feature` |
 | Experiment | `features/`, `type: experiment`; the result is a decision page |
 | Initiative | `wiki/synthesis/`, linking its features and decisions |
@@ -99,16 +99,11 @@ An experiment adds `## Hypothesis`, `## Metric` (a name from
 `metrics/definitions.yml`) and `## Result` once it has run.
 
 The wiki describes what *is*; `features/` describes what is *next*. A shipped
-feature goes `status: shipped` and is never deleted.
+feature goes `status: shipped`.
 
-## `tasks.md` — the ordered queue
+## `tasks.md` — open work only
 
 ```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 -->
@@ -116,7 +111,7 @@ horizon: 2026-10-13        # this file is stale after this date
 2. [ ] T002 Write the capture flows  needs:T001  ~3h
 
 ## Parallel                  <!-- independent, safe to batch -->
-- [ ] T004 [P] Move the SKU IDs into the wiki  ~1h
+- [ ] T004 Move the SKU IDs into the wiki  ~1h
 
 ## Blocked
 - [ ] T005 Submit the iOS build
@@ -125,14 +120,9 @@ horizon: 2026-10-13        # this file is stale after this date
 
 ## 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.
+Delete a task when it is done — the commit records it. No `## Done`, no session
+notes. Cap: 100 lines. A blocker with no 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.

package/standards/wiki-schema.md

@@ -1,299 +1,71 @@
-# Wiki — schema and rules
+# Wiki — rules
 
-This folder is a **Claude-maintained knowledge base** for the product. The model is the LLM-Wiki pattern: `.context/raw/` holds immutable sources, `.context/wiki/` holds synthesised pages with `[[wikilinks]]`, this file defines the schema.
+`.context/wiki/` holds what an agent would get wrong without being told. `.context/raw/` holds
+sources, never edited. Answer from the wiki, not from raw.
 
-**Read this file before creating or editing any page under `.context/wiki/`.**
+## The test
 
----
-
-## Three layers
-
-| Layer | Path | Mutability | Who writes |
-|---|---|---|---|
-| Raw | `.context/raw/`, `.context/designs/` | **Immutable** — never edit | Humans (or external systems) |
-| Wiki | `.context/wiki/` | Mutable, schema-bound | Claude (via `/zeno:ingest`, `/zeno:ask`, `/zeno:wiki-lint`) |
-| Index | `.context/wiki/index.md` | Auto-maintained | `/zeno:ingest` and `/zeno:wiki-lint` |
-
-The wiki is the **only** layer Claude reads for `/zeno:ask`. Never answer from `.context/raw/` directly — the synthesis must be written down or it doesn't exist.
-
----
+Keep a line only if an agent would make a mistake without it. Never write what the
+code, an HTML design, or `git log` already says. Describe what is true **now**:
+history is git's job.
 
-## Page types
-
-Every page in `.context/wiki/` belongs to exactly one type. The folder name is the type.
-
-| Type | Folder | What it owns | Example |
-|---|---|---|---|
-| `concept` | `concepts/` | An idea, principle, or invariant. Prose-shaped. | `offline-first`, `money-in-minor-units` |
-| `entity` | `entities/` | A thing with canonical values (price, name, enum). Table-shaped. | `plan-pro`, `plan-free` |
-| `surface` | `surfaces/` | One screen / route / email / callable. Links to a raw wireframe. | `onboarding-welcome` |
-| `flow` | `flows/` | A user journey. Ordered list of `[[surface]]` steps. | `new-user-to-first-save` |
-| `decision` | `decisions/` | One ADR. Filename = `YYYY-MM-DD-slug.md`. Append-only. | `2026-06-24-annual-plan-only` |
-| `synthesis` | `synthesis/` | Cross-cutting page built from many entities/concepts. Refreshable. | `pricing`, `launch-checklist` |
-
-A page cannot be two types. If it feels like it is, it's two pages — split it.
-
-A product adds a type in `.claude/zeno.yaml`, with the reason and the `## `
-sections every page of it must have:
-
-```yaml
-wiki:
-  types:
-    - { type: postmortem, folder: postmortems, reason: …, sections: [Summary, Timeline, Root cause, Fix, Sources] }
-```
+## Folders
 
-`zeno check` fails a page of that type that misses a section. Its ID is
-`<TYPE>.<SLUG>` (`POSTMORTEM.MIDNIGHT-RESET`). The six built-in types and their
-folders cannot be redefined. Try the six first — an added type is a shape every
-reader and every product must learn.
-
-### Data sources
-
-Each tool that holds product data (Datadog, Sentry, Snowflake, an analytics
-console) is one `entity` page, `id: SOURCE.<NAME>`, in `entities/`:
-
-```markdown
-## Summary
-What this source holds, in one sentence.
-
-## Canonical values
-| Key | Value | Last changed |
+| Folder | Holds | Example |
 |---|---|---|
-| SOURCE.SENTRY.PROJECT | streaks-mobile | 2026-10-23 |
-| SOURCE.SENTRY.ACCESS | mcp: sentry | 2026-10-23 |
+| `concepts/` | a rule or invariant | `money-in-minor-units` |
+| `entities/` | canonical values (prices, SKUs, limits) — the one home for each | `plan-pro` |
+| `decisions/` | one file per topic: the current choice | `pricing` |
+| `surfaces/` | a screen's notes: what its HTML can't show (only screens that have some) | `paywall` |
+| `synthesis/` | research and cross-cutting analysis | `tax-table-verification-ay-2026-27` |
 
-## How to query
-The claims this source can answer, and one example query for each.
-```
+There is no page per screen: the HTML design is the screen spec. A screen gets a
+`surfaces/<slug>.md` only when it has a constraint or decision invisible in its pixels;
+the design set's notes button shows it, and `routes.js` sets `notes: null` for every
+other screen. A user journey worth keeping is a concept.
+A product may add a folder in `.claude/zeno.yaml` under `wiki.types`, with a reason.
 
-zeno has no connector of its own. The repo picks what does the reading, and
-`ACCESS` names it: `mcp: <server>`, `skill: <name>`, `cli: <command>`, or
-`manual: <where>` for a dashboard with no API, which a person reads and pastes
-into `raw/`. A `cli:` must also be in `doctor.tools` in `.claude/zeno.yaml`, so `zeno doctor`
-reports when it is missing. `zeno check` fails a source page that breaks either
-rule or has no `## How to query`. Never put a key or token on the page.
+## Pages
 
-The weigh gate reads sources to check a claim (C-14). Every query follows these
-rules:
+- Frontmatter: `last-verified: YYYY-MM-DD` is the only required field. `id` is kept
+  where code references it (`SOURCE.*`, entity keys).
+- Write only the sections you have something to say in. No `TBD`, no `none yet`.
+- One file per topic, edited in place. No dated names, no `v2`, no supersede chains.
+- Caps: page 60 lines, decision 30. Synthesis is exempt.
+- Link with `[[slug]]` (the file name without `.md`). `index.md` is one line per page.
 
-- **Read only.** Never create, change or delete anything in the source.
-- **Small.** One or two queries per claim, with a row limit. Some sources bill
-  per query.
-- **No user data in git.** Save counts, totals and rates, never rows that name
-  a person, an email or a device. Results that back a decision go to
-  `raw/YYYY-MM-DD-<source>-<slug>.md`: the query, the date and the numbers.
+## Decisions
 
----
-
-## Frontmatter (mandatory)
-
-Every page begins with YAML frontmatter:
-
-```yaml
----
-id: PLAN.PRO                  # Stable, uppercase, dot-separated. Never changes. Referenced from code.
-type: entity                  # concept | entity | surface | flow | decision | synthesis
-status: canonical             # canonical | draft | superseded
-last-verified: 2026-06-24     # ISO date. /zeno:wiki-lint flags pages > 90 days.
-supersedes: []                # IDs this page replaces (decisions only)
-superseded-by: null           # If non-null, this page is no longer canonical
----
-```
-
-### ID conventions
-
-| Type | ID shape | Example |
-|---|---|---|
-| concept | `CONCEPT.<SLUG>` | `CONCEPT.OFFLINE-FIRST` |
-| entity | `<DOMAIN>.<NAME>` | `PLAN.PRO`, `PLAN.FREE` |
-| surface | `SURFACE.<APP>.<PATH>` | `SURFACE.MOBILE.ONBOARDING.WELCOME` |
-| flow | `FLOW.<SLUG>` | `FLOW.NEW-USER-TO-FIRST-SAVE` |
-| decision | `DECISION.<YYYY-MM-DD>.<SLUG>` | `DECISION.2026-06-24.ANNUAL-PLAN-ONLY` |
-| synthesis | `SYNTHESIS.<SLUG>` | `SYNTHESIS.PRICING` |
-
-Once assigned, an ID never changes. If a page is renamed, the ID stays. If the thing it describes is killed, mark `status: superseded` and set `superseded-by`; do not delete.
-
----
-
-## Page body — required sections
-
-Each type has a required section list. `/zeno:wiki-lint` fails the page if any are missing.
-
-### `concept`
 ```markdown
-## Summary
-One sentence — what the concept is.
-
-## Why it matters
-Why this is a load-bearing idea. Tie it to a constraint, an incident, or a principle.
-
-## Implications
-Bulleted: what this forces / forbids in practice.
-
-## Related
-- [[other-concept]] — relationship
-- [[entity-x]] — where this applies
-
-## Sources
-- .context/raw/<source> or .context/designs/<surface>/<flow>/<screen>.html
-```
-
-### `entity`
-```markdown
-## Summary
-One sentence — what this entity is.
-
-## Canonical values
-| Key | Value | Last changed |
-|---|---|---|
-| PRICE.PRO.YEARLY | $49 | 2026-04-12 |
-| STORAGE.PRO | 5 GB | 2026-04-12 |
-
-## Related
-- [[concept-x]] — concept this entity instantiates
-- [[entity-y]] — sibling / upgrade-from
-
-## Sources
-- .context/raw/<source>
-```
-
-The `Canonical values` table is the single source of truth. Any value here that disagrees with the codebase is a bug — fix the code or update this page.
-
-### `surface`
-```markdown
-## Summary
-One sentence — what this screen does.
-
-## Raw wireframe
-- .context/designs/<surface>/<flow>/<screen>.html
-
-## Copy
-Verbatim user-visible strings. Each must pass the [[copy-voice]] rules.
-
-## Flows that touch this surface
-- [[new-user-to-first-save]] — step 4
-
-## Entities referenced
-- [[plan-free]]
-- [[privacy-consent]]
-
-## Sources
-- .context/raw/<source>
-```
-
-### `flow`
-```markdown
-## Summary
-One sentence — what journey this is.
-
-## Audience
-end-user | admin
-
-## Entry
-Where the user arrives from.
-
-## Steps
-| # | Step | Surface | Notes |
-|---|---|---|---|
-| 1 | Welcome | [[welcome]] | First launch |
-| 2 | Sign up | [[sign-up]] | Email |
-| ... |
-
-## Exit
-The success state.
-
-## Escapes
-Back-button, skips, abandonment outcomes.
-
-## Sources
-- .context/raw/<source>
-```
-
-### `decision`
-```markdown
-## Decision
-One-line statement.
-
-## Why
-The motivation. Cite the trigger — incident, user feedback, regulator, scope cut.
-
-## Impact
-What changes downstream. Which [[entities]] / [[surfaces]] / [[concepts]] update.
-
-## Status
-Active | Superseded by [[decision-id]]
-
-## Sources
-- .context/raw/<source>
-```
-
-Decisions are append-only. To reverse a decision, write a new one with `supersedes: [DECISION.<old>]` and mark the old one's `superseded-by`.
-
-### `synthesis`
-```markdown
-## Summary
-What this synthesis combines.
-
-## Built from
-- [[entity-x]]
-- [[entity-y]]
-- [[concept-z]]
-
-## Body
-The cross-cutting answer. Every claim links back to a source page.
-
-## Last refresh
-2026-06-24 — refresh when any "Built from" page changes.
-
-## Sources
-- (synthesis pages cite wiki pages, not raw files)
-```
-
-Synthesis pages are **derived**. If a source page changes, `/zeno:wiki-lint` marks the synthesis stale.
-
 ---
-
-## Linking
-
-- Use `[[page-slug]]` — the filename without `.md`. Match the file exactly (case-sensitive on case-sensitive filesystems).
-- Cross-folder links use the slug, not the path: `[[tier-self]]`, not `[[entities/tier-self]]`.
-- An `[[unknown-link]]` is a TODO marker — `/zeno:wiki-lint` reports it. Never silently delete a broken link; either create the target page or rename the link.
-- The `Related` section is what makes the graph navigable. Every page must have at least two outbound links (or be flagged as orphan-source).
-
+last-verified: 2026-10-27
 ---
+# Pricing
+**Choice:** annual plan only, ₹249 ([[plan-pro]]).
+**Why:** monthly churn was 3× annual in the 2026-06 test.
+**Rejected:** monthly plan (churn) · lifetime deal (no recurring revenue).
+```
 
-## Lint rules (what `/zeno:wiki-lint` enforces)
-
-| Rule | Failure |
-|---|---|
-| Missing required section | Block — must be fixed |
-| `[[wikilink]]` to a non-existent page | Block — create target or rename link |
-| Orphan page (zero inbound links) | Warn |
-| Two entities claim the same `id` | Block |
-| Two entities have contradictory canonical values for the same key | Block |
-| `last-verified` > 90 days | Warn |
-| `status: superseded` without `superseded-by` | Block |
-| Source file in `.context/raw/` not referenced by any wiki page | Warn |
-| Synthesis page where a `Built from` page changed after `Last refresh` | Warn |
-| Filename does not match the `id`'s slug portion | Block |
+When the choice changes, overwrite the file. `Rejected:` is what stops the same idea
+being proposed again; keep it. Fix lists and audit results go in commit messages or
+`CHANGELOG.md`, not here.
 
-`/zeno:wiki-lint --fix` auto-fixes: filename ↔ id mismatches, missing `last-verified` (sets to today if the page is touched), index regeneration.
+## Data sources
 
----
+Each tool that holds product data is one entity page, `id: SOURCE.<NAME>`, with a
+`## How to query` section and a `SOURCE.<NAME>.ACCESS` row: `mcp: <server>`,
+`skill: <name>`, `cli: <command>` (also listed in `doctor.tools`) or `manual: <where>`.
+Queries are read-only, one or two per claim, with a row limit. Save counts and
+rates to `raw/YYYY-MM-DD-<source>-<slug>.md`, never rows that name a person. Never
+put a key or token on the page.
 
-## What the wiki is NOT for
+## Not for
 
-- **Not for code documentation.** Docstrings stay in code. The wiki is product-shaped, not API-shaped.
-- **Not for transient task tracking.** Use `TaskCreate` / PR descriptions / commit messages for ephemeral work.
-- **Not for chat logs.** If a chat produces a decision, write a `decision` page; throw the chat away.
-- **Not for drafts of code.** If it would be a comment, it's a comment.
-
----
+Code docs (they go next to the code) · tasks (`tasks.md`) · plans (`features/`) ·
+chat logs · session notes · changelogs.
 
-## Source of truth
+## Checked by `zeno check`
 
-`.context/wiki/` is the canonical knowledge base, and every page in it follows
-the schema above — there are no plan-shaped exceptions. What is *next* lives in
-`.context/features/`, and the ordered queue lives in `.context/tasks.md`; the
-wiki describes what is, not what is planned. The repo root holds no
-product-knowledge `.md` files.
+`wiki-frontmatter` (last-verified, placeholders, stale > 90 days) · `context-size`
+(caps, dated decision names, no `flows/`) · `canonical-values` (a
+price in a decision or screen note is held by an entity) · `sources`.