@freetesh/zeno 0.7.0 → 0.8.0

package/.claude-plugin/marketplace.json

@@ -7,8 +7,8 @@
     {
       "name": "zeno",
       "source": "./",
-      "description": "Shared standards, searchable product knowledge and decision checks for every product repo."
+      "description": "Keeps your domain knowledge and AI rules local and enforces them, so Claude hallucinates less."
     }
   ],
-  "description": "zeno: standards, searchable product knowledge and a decision gate for Claude Code."
+  "description": "zeno: Keep your domain knowledge and AI rules in your repo, and enforce them. Less AI guessing, faster delivery."
 }

package/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "zeno",
-  "version": "0.7.0",
-  "description": "Shared standards, searchable product knowledge and decision checks for every product repo.",
+  "version": "0.8.0",
+  "description": "Keeps your domain knowledge and AI rules local and enforces them, so Claude hallucinates less.",
   "author": {
     "name": "Ritesh Firodiya",
     "email": "40817224+ritesh-firodiya@users.noreply.github.com"

package/README.md

@@ -1,9 +1,10 @@
 # zeno
 
-Standards, searchable product knowledge and a decision gate for teams that
-build with Claude Code. zeno keeps several products consistent as they evolve,
-keeps what you decided findable, and makes Claude weigh a request against your
-rules and history before it acts on it.
+A productivity tool for the whole product development lifecycle (PDLC), from
+idea to release. zeno keeps your domain knowledge, decisions and AI rules local,
+in your own repos, and enforces them: Claude searches them before it answers,
+weighs a request against them before it acts, and `zeno check` fails when code
+or docs break them. The AI hallucinates less, and your team ships faster.
 
 It has two halves that read the same config:
 
@@ -42,7 +43,7 @@ It has two halves that read the same config:
 
 ```bash
 # plugin (from GitHub)
-claude plugin marketplace add ritesh-firodiya/zeno-ai
+claude plugin marketplace add ritesh-firodiya/zeno
 claude plugin install zeno@zeno
 
 # CLI (Node 22+)
@@ -83,6 +84,11 @@ Run the CLI from source (Node 23.6+ runs the TypeScript directly):
 `pnpm install && ln -s "$PWD/cli/src/index.ts" ~/.local/bin/zeno`.
 `pnpm test`, `pnpm typecheck` and `pnpm build` run from the repo root.
 
+**Releasing.** Bump `version` in `package.json` and `.claude-plugin/plugin.json`,
+then push or merge to `main`. The `release` workflow runs the tests, publishes
+`@freetesh/zeno` to npm, tags `vX.Y.Z` and creates the GitHub release. A push
+without a bump releases nothing. It needs the `NPM_TOKEN` Actions secret.
+
 ## CLI
 
 ```bash
@@ -117,13 +123,22 @@ commands:                           # your own checkers, run by `zeno check`
 doctor:
   tools:
     - { tool: pnpm, why: product scripts, hint: npm i -g pnpm }
+wiki:
+  types:                            # added to the six built-in page types
+    - type: postmortem
+      folder: postmortems
+      reason: incidents need a timeline and a fix
+      sections: [Summary, Timeline, Root cause, Fix, Sources]   # zeno check requires each `## ` heading
+context:
+  folders:                          # added to the ten .context folders
+    - { folder: research, reason: interview notes, kept apart from raw/ }
 ```
 
 ```yaml
 # <repo>/.claude/zeno.yaml — written by `zeno init`
 zeno: 0.6.0
 kind: expo-app                      # expo-app | web | content
-modules: [docs, knowledge, metrics, code, listing]   # all optional; design is added when .context/designs exists
+modules: [docs, knowledge, code, listing]   # all optional; design is added when .context/designs exists, metrics only when asked
 packs: [expo]
 checks:
   stale-copies: { enabled: false, reason: "Cursor is still used here" }
@@ -132,7 +147,8 @@ weigh:
 ```
 
 Scalars: the most specific layer wins. `packs` and `standards` add up across
-layers; `commands` and `doctor.tools` merge by id. A check turned off must
+layers; `commands`, `doctor.tools`, `wiki.types` and `context.folders` merge
+by name. Built-in types and folders cannot be removed or redefined. A check turned off must
 carry a `reason:`, and `zeno check` lists every override.
 
 ## Standards
@@ -152,12 +168,12 @@ your own.
 
 ## Evals
 
-`evals/` runs five requests against a fixture product (`evals/fixtures/streaks`)
+`evals/` runs seven requests against a fixture product (`evals/fixtures/streaks`)
 with and without the plugin, each in a sandbox seeded with the fixture and a
 local QMD index:
 
 ```bash
-claude plugin eval . --scaffold --mocks off --allow-tools 'mcp__plugin_zeno_qmd__*' --runs 2
+claude plugin eval . --scaffold --mocks off --allow-tools 'mcp__plugin_zeno_qmd__*' Write Edit --runs 2
 ```
 
 ## Layout
@@ -165,7 +181,7 @@ claude plugin eval . --scaffold --mocks off --allow-tools 'mcp__plugin_zeno_qmd_
 ```
 .claude-plugin/   plugin manifest and marketplace
 skills/           weigh, standards, ask, ingest, decision, wiki-lint
-agents/           challenger — independent second opinion for large requests
+agents/           challenger — independent second opinion for too-large requests
 hooks/            session start: constitution titles, qmd refresh
 standards/        default standards
 packs/            vendor doc packs

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

@@ -1,6 +1,6 @@
 import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
-const ALLOWED_FOLDERS = ["raw", "wiki", "features", "designs", "listing", "marketing", "metrics", "support", "legal", "ops"];
+import { CONTEXT_FOLDERS } from "../config/schema.js";
 const KNOWLEDGE_CONTEXT = ["raw", "wiki", "features"];
 /** What .context must hold: README.md and tasks.md always, the knowledge folders only when docs or knowledge is on. */
 export function requiredContext(modules) {
@@ -11,7 +11,7 @@ const ROOT_FILES = ["README.md", "tasks.md"];
 export const contextLayout = {
     id: "context-layout",
     module: null,
-    description: ".context/ has the required folders, only the ten allowed ones, and only README.md + tasks.md at its root",
+    description: ".context/ has the required folders, only the allowed ones (the ten plus context.folders), and only README.md + tasks.md at its root",
     run({ repo, config }) {
         const context = join(repo, ".context");
         const finding = (level, file, message) => ({
@@ -23,11 +23,12 @@ export const contextLayout = {
         if (!existsSync(context))
             return [finding("error", ".context", "no .context/ folder — run `zeno init`")];
         const findings = requiredContext(config.modules).filter((name) => !existsSync(join(context, name))).map((name) => finding("error", `.context/${name}`, `required ${name} is missing`));
+        const allowed = [...CONTEXT_FOLDERS, ...config.context.folders.map((entry) => entry.folder)];
         for (const entry of readdirSync(context, { withFileTypes: true })) {
             if (entry.name === ".DS_Store")
                 continue;
-            if (entry.isDirectory() && !ALLOWED_FOLDERS.includes(entry.name)) {
-                findings.push(finding("error", `.context/${entry.name}`, `${entry.name}/ is not one of the ten folders`));
+            if (entry.isDirectory() && !allowed.includes(entry.name)) {
+                findings.push(finding("error", `.context/${entry.name}`, `${entry.name}/ is not an allowed folder — move it, or add it under context.folders in zeno.yaml`));
             }
             if (entry.isFile() && !ROOT_FILES.includes(entry.name)) {
                 findings.push(finding("error", `.context/${entry.name}`, "only README.md and tasks.md may sit at .context/ root"));

package/cli/dist/checks/index.js

@@ -3,6 +3,7 @@ import { canonicalValues } from "./canonical-values.js";
 import { contextLayout } from "./context-layout.js";
 import { staleCopies, standardsCopies } from "./copies.js";
 import { commandChecks } from "./external.js";
+import { metricsDefinitions } from "./metrics.js";
 import { wikiFrontmatter } from "./wiki-frontmatter.js";
 export const ALL_CHECKS = [
     contextLayout,
@@ -11,5 +12,6 @@ export const ALL_CHECKS = [
     standardsCopies,
     staleCopies,
     architecture,
+    metricsDefinitions,
     commandChecks,
 ];

package/cli/dist/checks/metrics.js

@@ -0,0 +1,14 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+const DEFINITIONS = ".context/metrics/definitions.yml";
+export const metricsDefinitions = {
+    id: "metrics-definitions",
+    module: "metrics",
+    description: "metrics/definitions.yml names the numbers the weigh gate measures value against",
+    run({ repo }) {
+        if (existsSync(join(repo, DEFINITIONS)))
+            return [];
+        // A warning: most products turn metrics on before they define a single number.
+        return [{ check: "metrics-definitions", level: "warn", file: DEFINITIONS, message: "no metric definitions — the weigh gate cannot name the metric a request moves" }];
+    },
+};

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

@@ -2,15 +2,8 @@ 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"];
-const FOLDER_BY_TYPE = {
-    concept: "concepts",
-    entity: "entities",
-    surface: "surfaces",
-    flow: "flows",
-    decision: "decisions",
-    synthesis: "synthesis",
-};
 const STALE_AFTER_DAYS = 90;
 const DAY_MS = 86_400_000;
 const NOT_PAGES = ["index.md", "CLAUDE.md"];
@@ -26,13 +19,16 @@ 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",
-    run({ repo, today }) {
+    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.
+        const sectionsByType = new Map(config.wiki.types.map((entry) => [entry.type, entry.sections]));
         const findings = [];
         const add = (level, file, message) => findings.push({ check: "wiki-frontmatter", level, file, message });
         const filesById = new Map();
         const stale = [];
         for (const file of wikiPages(repo)) {
-            const { data } = parseFrontmatter(readFileSync(join(repo, file), "utf8"));
+            const { data, body } = parseFrontmatter(readFileSync(join(repo, file), "utf8"));
             if (!data) {
                 add("error", file, "no frontmatter");
                 continue;
@@ -41,9 +37,16 @@ export const wikiFrontmatter = {
             if (missing.length > 0)
                 add("error", file, `missing ${missing.join(", ")}`);
             const folder = file.split("/")[2];
-            const expected = FOLDER_BY_TYPE[String(data.type)];
+            const expected = folderByType[String(data.type)];
             if (data.type && expected !== folder)
                 add("error", file, `type ${data.type} does not belong in ${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()] : [])));
+                const absent = sections.filter((section) => !headings.has(section));
+                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 verified = asDate(data["last-verified"]);

package/cli/dist/commands/init.js

@@ -22,7 +22,7 @@ async function askAnswers(inferred, packs) {
     if (cancelled(kind))
         return null;
     const modules = await prompts.multiselect({
-        message: "Which modules? All optional. (docs = wiki, design = HTML designs, knowledge = search, specs, metrics, code = LSP, architecture, listing)",
+        message: "Which modules? All optional. (docs = wiki, design = HTML designs, knowledge = search, metrics = definitions.yml, code = LSP, architecture, listing)",
         initialValues: inferred.config.modules,
         options: MODULES.map((value) => ({ value, label: value })),
         required: false,

package/cli/dist/config/load.js

@@ -62,7 +62,8 @@ function mergeBy(lists, key) {
 /**
  * Reads the estate, product and local zeno.yaml layers over defaults inferred
  * from the repo. Scalars: the most specific layer wins. Lists of names add up
- * (packs, standards); lists of records merge by their key (commands, tools).
+ * (packs, standards); lists of records merge by their key (commands, tools,
+ * wiki types, context folders).
  */
 export function loadConfig(repo, options = {}) {
     const estateRoot = options.estateRoot === undefined ? findEstate(dirname(resolve(repo))) : options.estateRoot;
@@ -86,6 +87,8 @@ export function loadConfig(repo, options = {}) {
         doctor: { tools: mergeBy(pick("doctor").map((doctor) => doctor?.tools ?? []), (tool) => tool.tool) },
         checks: Object.assign({}, ...pick("checks")),
         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) },
     };
     if (Object.keys(config.expo ?? {}).length === 0)
         delete config.expo;

package/cli/dist/config/schema.js

@@ -1,6 +1,17 @@
 import { z } from "zod";
 export const KINDS = ["expo-app", "web", "content"];
-export const MODULES = ["docs", "design", "knowledge", "specs", "metrics", "code", "architecture", "listing"];
+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`. */
+export const WIKI_FOLDER_BY_TYPE = {
+    concept: "concepts",
+    entity: "entities",
+    surface: "surfaces",
+    flow: "flows",
+    decision: "decisions",
+    synthesis: "synthesis",
+};
+/** 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
     .object({ enabled: z.boolean().default(true), reason: z.string().min(1).optional() })
     .refine((check) => check.enabled || check.reason !== undefined, {
@@ -16,6 +27,22 @@ const command = z
     if: z.string().optional(),
 })
     .strict();
+const kebab = z.string().regex(/^[a-z0-9-]+$/, "use lowercase-kebab");
+/** An addition to zeno's layout says why, so products drifting apart is written down. */
+const reason = z.string().min(1);
+const wikiType = z
+    .object({
+    type: kebab,
+    folder: kebab,
+    reason,
+    /** The `## ` headings every page of this type must have, as the schema lists them for the built-in six. */
+    sections: z.array(z.string().min(1)).min(1, "list the `## ` sections every page of this type must have"),
+})
+    .strict()
+    .refine((entry) => !(entry.type in WIKI_FOLDER_BY_TYPE) && !Object.values(WIKI_FOLDER_BY_TYPE).includes(entry.folder), {
+    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 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
@@ -33,11 +60,13 @@ export const layerSchema = z
     doctor: z.object({ tools: z.array(tool) }).partial(),
     checks: z.record(z.string(), checkOverride),
     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(),
 })
     .partial()
     .strict();
 export const MODULES_BY_KIND = {
-    "expo-app": ["docs", "knowledge", "metrics", "code", "listing"],
-    web: ["docs", "knowledge", "metrics", "code"],
+    "expo-app": ["docs", "knowledge", "code", "listing"],
+    web: ["docs", "knowledge", "code"],
     content: ["docs", "knowledge"],
 };

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@freetesh/zeno",
-  "version": "0.7.0",
-  "description": "zeno CLI: set up, check and sync product repos against the shared standards.",
+  "version": "0.8.0",
+  "description": "zeno CLI: keep your domain knowledge and AI rules in your repo, and enforce them.",
   "license": "MIT",
   "author": "Ritesh Firodiya",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ritesh-firodiya/zeno-ai.git"
+    "url": "git+https://github.com/ritesh-firodiya/zeno.git"
   },
   "type": "module",
   "bin": {

package/skills/decision/SKILL.md

@@ -9,7 +9,7 @@ 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.
+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.

package/skills/ingest/SKILL.md

@@ -9,7 +9,7 @@ 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.
+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.
 
 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.
 
@@ -20,12 +20,13 @@ Source to ingest: `$ARGUMENTS`
    - 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.
+   - 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.
 
 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 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 (`../../standards/wiki-schema.md`, relative to this skill). Missing a required section is a lint failure.
+   - 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.
 

package/skills/weigh/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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".
+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 a change that spans 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
@@ -29,8 +29,10 @@ product's `.claude/zeno.yaml` may tighten this under `weigh.trivial`.
    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
+   the goal in plain words, then the key nouns, scoped with `collections` to
+   this product's `<repo>-wiki` and `<repo>-features` (the names `zeno init`
+   gives them; add `pack-<name>` when the question is about a vendor's API). Other products' hits are noise here; step 4 is where
+   siblings are searched. 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
@@ -52,6 +54,10 @@ product's `.claude/zeno.yaml` may tighten this under `weigh.trivial`.
      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".
+     When a number would settle it, check the product's `SOURCE.*` entity pages
+     for where that data lives and query it rather than guess.
+   - Evidence: say which evidence from `dev-methods.md` the work must leave — a
+     feature page, a failing test first, or a metric and snapshot.
 
 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
@@ -59,10 +65,13 @@ product's `.claude/zeno.yaml` may tighten this under `weigh.trivial`.
    → 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.
+7. **Too-large, or the user asked for a second opinion?** Then, and only then,
+   ask the `challenger` agent for an independent read. It costs tens of
+   thousands of tokens, so hand it what you already have: the request, the repo
+   path, your draft verdict, and every file and wiki page you read with one line
+   on what each says. It checks your reasoning and looks only where you did
+   not. Where you and it disagree, show both. A large request is weighed by you
+   alone.
 
 ## Verdict
 

package/skills/wiki-lint/SKILL.md

@@ -3,13 +3,13 @@ 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).
+You are linting the wiki at `.context/wiki/` against 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).
 
 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.
+1. **Read the wiki schema** 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,
@@ -29,13 +29,13 @@ Mode: `$ARGUMENTS` (empty = audit only; `--fix` = audit + auto-fix safe issues).
 
 | Check | Rule |
 |---|---|
-| Missing required section | Per the wiki schema (`../../standards/wiki-schema.md`, relative to this skill) § "Page body — required sections" |
+| 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. |
+| `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`. |
 
 ### Warnings
 

package/standards/README.md

@@ -9,5 +9,6 @@ replaces it; a configured `constitution.md` adds principles instead.
 |---|---|
 | `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 |
+| `context-layout.md` | The `.context/` ten-folder layout, where each kind of document lives, `features/` and `tasks.md` formats |
+| `dev-methods.md` | The evidence spec-, test- and data-driven work leaves behind |
 | `agent-contract.md` | What every agent does before, during and after work |

package/standards/context-layout.md

@@ -26,6 +26,9 @@ folder.
 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/`.
+   A product that truly needs another folder adds it in `.claude/zeno.yaml`,
+   with the reason: `context: { folders: [{ folder: research, reason: … }] }`.
+   The ten cannot be removed.
 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
@@ -54,6 +57,26 @@ folder.
 - Frontmatter follows the wiki schema: `id`, `type`, `status`, `last-verified`,
   `supersedes`, `superseded-by`. Kebab-case keys.
 
+## Where each kind of document lives
+
+Teams name documents many ways. Each name maps to one home; there is no
+separate folder per name.
+
+| Document | Home |
+|---|---|
+| ADR | `wiki/decisions/`, `status: canonical` |
+| RFC | `wiki/decisions/`, `status: draft` — the same page becomes the ADR when accepted |
+| PRD | `features/`, `type: feature` |
+| Experiment | `features/`, `type: experiment`; the result is a decision page |
+| Initiative | `wiki/synthesis/`, linking its features and decisions |
+| Finding | the dated data in `raw/`; what it means in `wiki/synthesis/` or a concept |
+| Know-how | `wiki/concepts/`; `ops/` when it is a runbook |
+| Bug | the issue tracker; a wiki concept only when it teaches a rule |
+| Data source | `wiki/entities/` — see the wiki schema, "Data sources" |
+
+If a document fits none of these for a real product, add a wiki type or a
+folder in `.claude/zeno.yaml` with its reason — not a new convention by hand.
+
 ## `features/` — what is next
 
 One page per feature, `NNNN-<slug>.md`:
@@ -72,6 +95,9 @@ release: 3.4.0
 > One or two sentences users will read in the release notes.
 ```
 
+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.
 

package/standards/dev-methods.md

@@ -0,0 +1,29 @@
+# Development methods
+
+zeno does not run a method; it checks that the method left evidence a later
+reader (or the weigh gate) can follow. A team replaces this file with its own
+`dev-methods.md` in a configured standards folder.
+
+| Method | The evidence it leaves |
+|---|---|
+| Spec-driven | A `features/` page with acceptance scenarios, written before the code. Code and tests cite its ID (`FEAT-0031`) or a wiki ID (`FLOW.…`, `DECISION.…`). |
+| Test-driven | A test that failed before the change and passes after. Bug fixes start with the failing test. The test path goes in the feature page or decision. |
+| Data-driven | A named metric in `metrics/definitions.yml`, the query that measured it, and a dated snapshot in `raw/`. The decision cites the snapshot, not a memory of a dashboard. |
+
+## Which one, when
+
+- **New behaviour users see** → spec-driven: the feature page comes first.
+- **Logic that can break** (money, parsing, data writes, a bug fix) → test-driven.
+- **A bet on what users want** → data-driven: an experiment page with its metric
+  before the build, the result as a decision after.
+
+They combine. A paywall change is a spec (what users see), tests (the price
+logic) and an experiment (does conversion move).
+
+## Rules
+
+1. No evidence, not done. "It works" without a test, a scenario or a number is
+   an opinion.
+2. Evidence lives in the repo (C-03). A dashboard link alone is not evidence —
+   it changes; the snapshot in `raw/` does not.
+3. When a method keeps being skipped, make it a check (C-09), not a longer doc.

package/standards/wiki-schema.md

@@ -33,6 +33,44 @@ Every page in `.context/wiki/` belongs to exactly one type. The folder name is t
 
 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] }
+```
+
+`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 |
+|---|---|---|
+| SOURCE.SENTRY.PROJECT | streaks-mobile | 2026-10-23 |
+| SOURCE.SENTRY.ACCESS | Sentry MCP server | 2026-10-23 |
+
+## How to query
+The MCP server or CLI to use, and one example query. Results that back a
+decision are saved to `raw/YYYY-MM-DD-<source>-<slug>.md` so they can be re-read.
+```
+
+zeno has no connector of its own: the vendor's MCP server or CLI does the
+reading. Add it to `doctor.tools` in `.claude/zeno.yaml` so `zeno doctor`
+reports when it is missing. Never put a key or token on the page.
+
 ---
 
 ## Frontmatter (mandatory)