@freetesh/zeno 0.0.0-stage → 0.7.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "zeno",
+  "owner": {
+    "name": "Ritesh Firodiya"
+  },
+  "plugins": [
+    {
+      "name": "zeno",
+      "source": "./",
+      "description": "Shared standards, searchable product knowledge and decision checks for every product repo."
+    }
+  ],
+  "description": "zeno: standards, searchable product knowledge and a decision gate for Claude Code."
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "$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.",
+  "author": {
+    "name": "Ritesh Firodiya",
+    "email": "40817224+ritesh-firodiya@users.noreply.github.com"
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ritesh Firodiya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,176 @@
-# Temporary Holding Version
+# zeno
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+It has two halves that read the same config:
+
+- **a Claude Code plugin** — skills, a decision gate, a session hook and a
+  search server, so every session in every repo starts with the same rules;
+- **the `zeno` CLI** — set up, check, sync and browse your repos.
+
+## What it does
+
+- **Weigh before acting.** For a non-trivial request Claude checks the
+  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`.
+- **Knowledge that is found, not remembered.** Every repo's `.context/wiki` and
+  feature board is indexed with [QMD](https://github.com/tobi/qmd) (local hybrid
+  search). Claude is told to search before answering.
+- **Standards with one home.** zeno ships defaults (constitution, wiki schema,
+  `.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.
+- **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
+  folder, since apps map `@/` to their own `src`). `zeno init` writes starters and
+  `.dependency-cruiser.base.cjs`, the shared base they extend; that base is zeno's,
+  and `zeno sync` keeps it current. Add `dependency-cruiser` as a devDependency.
+  `zeno check` fails on a broken boundary or a cycle, the gate weighs requests
+  against the rules, and `zeno ui` draws each repo's import graph.
+- **Products evolve together.** Packs index vendor docs (`llms.txt`) for a stack;
+  `zeno sync` refreshes them and moves each repo to the current zeno version.
+
+## Install
+
+```bash
+# plugin (from GitHub)
+claude plugin marketplace add ritesh-firodiya/zeno-ai
+claude plugin install zeno@zeno
+
+# CLI (Node 22+)
+npm install -g @freetesh/zeno
+
+# search
+npm install -g @tobilu/qmd --allow-scripts=node-llama-cpp,tree-sitter-go,tree-sitter-python,tree-sitter-rust,tree-sitter-typescript,tree-sitter-javascript
+
+# optional: write-less discipline for the efficiency step of the gate
+claude plugin marketplace add DietrichGebert/ponytail && claude plugin install ponytail@ponytail
+```
+
+## Quickstart (5 minutes)
+
+In any git repo, after the install above:
+
+```bash
+zeno doctor                 # node, git, qmd — fix anything marked ✗ first
+zeno init                   # pick kind, modules and doc packs; writes .claude/zeno.yaml and .context/
+zeno check                  # should print "<repo>  ok"
+zeno sync                   # fetches the packs you picked and indexes the wiki for search
+```
+
+Then start Claude Code in the repo. The session hook loads the constitution,
+and a non-trivial request is weighed before Claude acts on it — try
+`/zeno:weigh add a dark mode toggle`. Write decisions to `.context/wiki/` as
+you make them (`/zeno:decision`) and ask about them later with `/zeno:ask`.
+
+Want import rules too? `zeno init --force --modules docs,knowledge,architecture`
+(keep the modules you already had), `npm i -D dependency-cruiser`, then edit the
+starter `.dependency-cruiser.cjs` to your layers. `evals/fixtures/streaks` is a
+small product with a wiki and decision records, if you want to see the
+`.context/` layout before touching your own repo.
+
+For local development of zeno itself, link the repo as a skills-dir plugin so
+edits apply on the next session: `ln -s "$PWD" ~/.claude/skills/zeno`.
+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.
+
+## CLI
+
+```bash
+zeno init             # write .claude/zeno.yaml and the missing .context files (asks kind, modules, packs)
+zeno init -y --kind web --modules docs,code --packs nextjs   # same, no questions
+zeno add              # list packs; `zeno add expo` adds one and indexes its docs (-g: whole estate)
+zeno check            # this repo against the standards (exit 1 on any error)
+zeno check --all -q   # every repo in the estate, only the ones with findings
+zeno standards        # which standards apply here, and where each comes from
+zeno sync             # refresh pack docs + search index, move the pinned zeno version, then check
+zeno status           # version, kind, modules, config layers, check summary
+zeno doctor           # node, git, qmd — plus any tools your config lists
+zeno learn            # proposals from overridden verdicts; --approve/--reject <id>
+zeno weigh "<ask>"    # the decision gate from the terminal (runs Claude, weighs only)
+zeno ui               # every wiki (search, backlinks, graph) on :4610, design galleries on :4611
+```
+
+## Config
+
+`.claude/zeno.yaml`, read in layers — **estate → repo → local**
+(`zeno.local.yaml`, not committed). The estate is the nearest folder above a
+repo whose `zeno.yaml` says `estate: true`, or `ZENO_ESTATE`.
+
+```yaml
+# <estate>/.claude/zeno.yaml — shared by every repo below it
+estate: true
+standards: [.zeno/standards]        # team rules; same name replaces a zeno default
+commands:                           # your own checkers, run by `zeno check`
+  - id: designs
+    run: ./scripts/check-designs.sh
+    if: .context/designs            # only where this path exists
+doctor:
+  tools:
+    - { tool: pnpm, why: product scripts, hint: npm i -g pnpm }
+```
+
+```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
+packs: [expo]
+checks:
+  stale-copies: { enabled: false, reason: "Cursor is still used here" }
+weigh:
+  weights: { C-05: 2 }
+```
+
+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
+carry a `reason:`, and `zeno check` lists every override.
+
+## Standards
+
+| zeno default | What it holds |
+|---|---|
+| `constitution.md` | Principles C-01–C-13 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` |
+| `agent-contract.md` | What every agent does before, during and after work |
+
+## Packs
+
+`packs/<name>/pack.yaml` names the vendor docs to index. Shipped: expo,
+uniwind, react, nextjs, firebase, revenuecat. A pack is three lines of YAML; add
+your own.
+
+## Evals
+
+`evals/` runs five 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
+```
+
+## Layout
+
+```
+.claude-plugin/   plugin manifest and marketplace
+skills/           weigh, standards, ask, ingest, decision, wiki-lint
+agents/           challenger — independent second opinion for large requests
+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
+cli/              the zeno CLI (TypeScript, vitest; built to cli/dist for npm)
+evals/            plugin evals and the fixture product
+```

package/cli/dist/checks/architecture.js

@@ -0,0 +1,126 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join, posix } from "node:path";
+// The names dependency-cruiser itself looks for; `zeno init` writes the first.
+export const RULES_FILES = [".dependency-cruiser.cjs", ".dependency-cruiser.js", ".dependency-cruiser.mjs", ".dependency-cruiser.json"];
+const DEFAULT_COLLAPSE = "^(apps|packages)/[^/]+|^[^/]+/[^/]+";
+const SHOWN_PER_RULE = 3;
+// Mermaid refuses diagrams over 50k characters.
+const MERMAID_MAX_CHARS = 50_000;
+const MAX_BUFFER = 64 * 1024 * 1024;
+// Monorepo workspaces whose apps each map `@/` to their own src need one rules file each,
+// because dependency-cruiser resolves aliases from a single tsconfig per run.
+const WORKSPACE_PARENTS = ["apps", "packages"];
+function rulesFile(dir) {
+    return RULES_FILES.find((file) => existsSync(join(dir, file)));
+}
+/** Every rules file in the repo: the root's, then one per workspace under apps/ and packages/. */
+export function findRules(repo) {
+    const workspaces = WORKSPACE_PARENTS.flatMap((parent) => existsSync(join(repo, parent))
+        ? readdirSync(join(repo, parent), { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => `${parent}/${entry.name}`)
+            .sort()
+        : []);
+    return [".", ...workspaces].flatMap((dir) => {
+        const file = rulesFile(join(repo, dir));
+        return file ? [{ dir, file }] : [];
+    });
+}
+const fromRoot = (dir, path) => posix.normalize(posix.join(dir, path));
+// The repo's own pinned copy, never a global one, so every machine runs the same version.
+function depcruiseBin(repo) {
+    const bin = join(repo, "node_modules", ".bin", "depcruise");
+    return existsSync(bin) ? bin : undefined;
+}
+function depcruise(repo, bin, rules, args) {
+    return spawnSync(bin, [".", "--config", rules.file, ...args], { cwd: join(repo, rules.dir), encoding: "utf8", maxBuffer: MAX_BUFFER });
+}
+// dependency-cruiser needs a TypeScript it supports (below 7) to read .ts files; without one it
+// skips them and still reports success, so a TypeScript workspace with none read is not a pass.
+function unreadTypeScript(repo, rules, modules) {
+    return existsSync(join(repo, rules.dir, "tsconfig.json")) && !modules.some((m) => /\.tsx?$/.test(m.source));
+}
+function typeScriptWarning(rules) {
+    const file = fromRoot(rules.dir, "tsconfig.json");
+    const message = "no TypeScript files were read, so their imports went unchecked — dependency-cruiser needs `typescript` below 7 installed here";
+    return [{ check: "architecture", level: "warn", file, message }];
+}
+/** One finding per broken rule: how often, and the first few places. */
+export function summarize(violations) {
+    const byRule = new Map();
+    for (const violation of violations.filter((v) => v.rule.severity === "error" || v.rule.severity === "warn")) {
+        byRule.set(violation.rule.name, [...(byRule.get(violation.rule.name) ?? []), violation]);
+    }
+    return [...byRule].map(([name, list]) => {
+        const shown = list.slice(0, SHOWN_PER_RULE).map((v) => (v.from === v.to ? v.from : `${v.from} → ${v.to}`));
+        const more = list.length > SHOWN_PER_RULE ? ` and ${list.length - SHOWN_PER_RULE} more` : "";
+        return {
+            check: "architecture",
+            level: list[0].rule.severity === "error" ? "error" : "warn",
+            file: list[0].from,
+            message: `${name} (${list.length}): ${shown.join(", ")}${more}`,
+        };
+    });
+}
+export const architecture = {
+    id: "architecture",
+    module: "architecture",
+    description: "the repo keeps the import boundaries in its own .dependency-cruiser.cjs",
+    run({ repo }) {
+        const finding = (message, file) => [{ check: "architecture", level: "error", file, message }];
+        const all = findRules(repo);
+        if (all.length === 0) {
+            return finding("no architecture rules — run `zeno init --force --modules ...,architecture` for a starter, or write one", RULES_FILES[0]);
+        }
+        const bin = depcruiseBin(repo);
+        if (!bin)
+            return finding("dependency-cruiser is not installed here — add it as a devDependency (e.g. `pnpm add -D dependency-cruiser`)", "package.json");
+        return all.flatMap((rules) => {
+            const result = depcruise(repo, bin, rules, ["--output-type", "json"]);
+            try {
+                const cruise = JSON.parse(result.stdout);
+                const findings = summarize(cruise.summary.violations.map((v) => ({ ...v, from: fromRoot(rules.dir, v.from), to: fromRoot(rules.dir, v.to) })));
+                return unreadTypeScript(repo, rules, cruise.modules) ? [...findings, ...typeScriptWarning(rules)] : findings;
+            }
+            catch {
+                const why = (result.error?.message ?? result.stderr).trim().split("\n").slice(-5).join(" ");
+                return finding(`dependency-cruiser failed: ${why}`, fromRoot(rules.dir, rules.file));
+            }
+        });
+    },
+};
+// The graph level is the repo's choice, kept where dependency-cruiser keeps it for its own high-level view.
+function collapsePattern(dir, file) {
+    try {
+        const config = createRequire(join(dir, "noop.js"))(join(dir, file));
+        return config.options?.reporterOptions?.archi?.collapsePattern ?? DEFAULT_COLLAPSE;
+    }
+    catch {
+        return DEFAULT_COLLAPSE;
+    }
+}
+function graphOf(repo, bin, rules) {
+    const collapse = collapsePattern(join(repo, rules.dir), rules.file);
+    // The graph shows the repo's own parts; npm packages would bury them (the rules still check npm imports).
+    const ownCode = "^(?!(\\.\\./)*node_modules/)";
+    const result = depcruise(repo, bin, rules, ["--output-type", "mermaid", "--collapse", collapse, "--include-only", ownCode]);
+    if (result.status !== 0 || !result.stdout.trim())
+        return undefined;
+    if (result.stdout.length > MERMAID_MAX_CHARS) {
+        return "flowchart LR\n  too_big[\"Graph too large to draw — set a coarser reporterOptions.archi.collapsePattern\"]";
+    }
+    return result.stdout.trim();
+}
+/** The repo's architecture as markdown — one mermaid graph per rules file — or undefined when there is nothing to draw. */
+export function architectureGraph(repo) {
+    const bin = depcruiseBin(repo);
+    if (!bin)
+        return undefined;
+    const sections = findRules(repo).flatMap((rules) => {
+        const graph = graphOf(repo, bin, rules);
+        return graph ? [`## ${rules.dir === "." ? "Whole repo" : rules.dir}\n\n\`\`\`mermaid\n${graph}\n\`\`\``] : [];
+    });
+    return sections.length > 0 ? sections.join("\n\n") : undefined;
+}

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

@@ -0,0 +1,46 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseFrontmatter } from "../lib/frontmatter.js";
+import { wikiPages } from "./wiki-frontmatter.js";
+const PRICE = /(?:[$₹€£]\s?\d[\d,]*(?:\.\d+)?)/g;
+const CODE_BLOCK = /```[\s\S]*?```/g;
+// An amount counts as a price only in a paragraph that talks about selling something;
+// "Ravi paid ₹6,200" in a bill-splitting app is an example, not a price.
+const PRICE_WORDS = /pric|cost|paywall|plan|tier|subscri|bundle|pack|purchase|buy|unlock|\/mo|per month|per year|annual|yearly|monthly/i;
+function amounts(text) {
+    return (text.match(PRICE) ?? []).map((price) => price.replace(/\s/g, ""));
+}
+function pricesIn(text) {
+    const paragraphs = text.replace(CODE_BLOCK, "").split(/\n\s*\n/);
+    return [...new Set(paragraphs.filter((paragraph) => PRICE_WORDS.test(paragraph)).flatMap(amounts))];
+}
+function heldAmounts(text) {
+    return amounts(text.replace(CODE_BLOCK, ""));
+}
+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)",
+    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
+        // example amounts (a tax product explains slabs with them).
+        return live
+            .filter((page) => page.data?.type === "surface")
+            .flatMap((page) => {
+            const orphans = pricesIn(page.body).filter((price) => !held.has(price));
+            if (orphans.length === 0)
+                return [];
+            return [
+                {
+                    check: "canonical-values",
+                    level: "warn",
+                    file: page.file,
+                    message: `${orphans.join(", ")} stated here but held by no entity page`,
+                },
+            ];
+        });
+    },
+};

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

@@ -0,0 +1,41 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+const ALLOWED_FOLDERS = ["raw", "wiki", "features", "designs", "listing", "marketing", "metrics", "support", "legal", "ops"];
+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) {
+    const knowledge = modules.includes("docs") || modules.includes("knowledge");
+    return ["README.md", "tasks.md", ...(knowledge ? KNOWLEDGE_CONTEXT : [])];
+}
+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",
+    run({ repo, config }) {
+        const context = join(repo, ".context");
+        const finding = (level, file, message) => ({
+            check: "context-layout",
+            level,
+            file,
+            message,
+        });
+        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`));
+        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.isFile() && !ROOT_FILES.includes(entry.name)) {
+                findings.push(finding("error", `.context/${entry.name}`, "only README.md and tasks.md may sit at .context/ root"));
+            }
+        }
+        if (existsSync(join(context, "raw")) && !existsSync(join(context, "raw", ".gitkeep"))) {
+            findings.push(finding("warn", ".context/raw/.gitkeep", "raw/ needs its .gitkeep so it survives a clean clone"));
+        }
+        return findings;
+    },
+};

package/cli/dist/checks/copies.js

@@ -0,0 +1,73 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+// Instruction files for agents other than Claude Code. They are copies of
+// AGENTS.md that nobody reads, so they only drift.
+const OTHER_AGENT_FILES = [".github/copilot-instructions.md", ".cursorrules", ".windsurfrules"];
+// Fraction of a shared standard's lines that must appear in a product file
+// before it counts as a copy rather than a reference.
+const COPY_THRESHOLD = 0.6;
+const STANDARD_COPIES = [{ file: ".context/wiki/CLAUDE.md", standard: "standards/wiki-schema.md" }];
+export const staleCopies = {
+    id: "stale-copies",
+    module: null,
+    description: "no instruction files for agents that are not used (Copilot, Cursor, Windsurf)",
+    run({ repo }) {
+        return OTHER_AGENT_FILES.filter((file) => existsSync(join(repo, file))).map((file) => ({
+            check: "stale-copies",
+            level: "warn",
+            file,
+            message: "instructions for an agent not in use — delete, Claude reads AGENTS.md",
+        }));
+    },
+};
+function meaningfulLines(text) {
+    return new Set(text
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0 && !line.startsWith("<!--")));
+}
+function sharedFraction(standard, candidate) {
+    const wanted = meaningfulLines(standard);
+    const present = meaningfulLines(candidate);
+    const shared = [...wanted].filter((line) => present.has(line)).length;
+    return wanted.size === 0 ? 0 : shared / wanted.size;
+}
+export const standardsCopies = {
+    id: "standards-copies",
+    module: null,
+    description: "shared rules and skills come from zeno, not from a copy in the product",
+    run({ repo, zenoRoot }) {
+        const findings = [];
+        for (const { file, standard } of STANDARD_COPIES) {
+            const productFile = join(repo, file);
+            const standardFile = join(zenoRoot, standard);
+            if (!existsSync(productFile) || !existsSync(standardFile))
+                continue;
+            const fraction = sharedFraction(readFileSync(standardFile, "utf8"), readFileSync(productFile, "utf8"));
+            if (fraction >= COPY_THRESHOLD) {
+                findings.push({
+                    check: "standards-copies",
+                    level: "warn",
+                    file,
+                    message: `${Math.round(fraction * 100)}% copy of zeno ${standard} — replace with a pointer`,
+                });
+            }
+        }
+        const zenoSkills = join(zenoRoot, "skills");
+        const productSkills = join(repo, ".claude", "skills");
+        if (existsSync(zenoSkills) && existsSync(productSkills)) {
+            const provided = new Set(readdirSync(zenoSkills));
+            for (const skill of readdirSync(productSkills)) {
+                if (!provided.has(skill))
+                    continue;
+                findings.push({
+                    check: "standards-copies",
+                    level: "warn",
+                    file: `.claude/skills/${skill}`,
+                    message: `zeno provides this as zeno:${skill} — delete the product copy`,
+                });
+            }
+        }
+        return findings;
+    },
+};

package/cli/dist/checks/external.js

@@ -0,0 +1,30 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+const MAX_OUTPUT_LINES = 15;
+function tail(text) {
+    return text.trim().split("\n").slice(-MAX_OUTPUT_LINES).join("\n");
+}
+/**
+ * Runs each checker a repo or its estate declares under `commands:` in
+ * zeno.yaml. zeno does not know what they check; a non-zero exit is an error
+ * reported under the command's own id.
+ */
+export const commandChecks = {
+    id: "commands",
+    module: null,
+    description: "every checker declared under `commands:` in zeno.yaml passes",
+    run({ repo, config }) {
+        return config.commands
+            .filter((command) => !command.if || existsSync(join(repo, command.if)))
+            .flatMap((command) => {
+            const result = spawnSync("sh", ["-c", command.run], { cwd: repo, encoding: "utf8" });
+            if (result.error) {
+                return [{ check: command.id, level: "error", file: command.if, message: `could not run: ${result.error.message}` }];
+            }
+            if (result.status === 0)
+                return [];
+            return [{ check: command.id, level: "error", file: command.if, message: tail(`${result.stdout}\n${result.stderr}`) }];
+        });
+    },
+};

package/cli/dist/checks/index.js

@@ -0,0 +1,15 @@
+import { architecture } from "./architecture.js";
+import { canonicalValues } from "./canonical-values.js";
+import { contextLayout } from "./context-layout.js";
+import { staleCopies, standardsCopies } from "./copies.js";
+import { commandChecks } from "./external.js";
+import { wikiFrontmatter } from "./wiki-frontmatter.js";
+export const ALL_CHECKS = [
+    contextLayout,
+    wikiFrontmatter,
+    canonicalValues,
+    standardsCopies,
+    staleCopies,
+    architecture,
+    commandChecks,
+];

package/cli/dist/checks/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,71 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { listFiles } from "../lib/files.js";
+import { parseFrontmatter } from "../lib/frontmatter.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"];
+const OLDEST_SHOWN = 3;
+export function wikiPages(repo) {
+    return listFiles(repo, ".context/wiki", (name) => name.endsWith(".md") && !NOT_PAGES.includes(name));
+}
+function asDate(value) {
+    const date = value instanceof Date ? value : new Date(String(value));
+    return Number.isNaN(date.getTime()) ? null : date;
+}
+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 }) {
+        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"));
+            if (!data) {
+                add("error", file, "no frontmatter");
+                continue;
+            }
+            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 = FOLDER_BY_TYPE[String(data.type)];
+            if (data.type && expected !== folder)
+                add("error", file, `type ${data.type} does not belong in ${folder}/`);
+            if (data.status === "superseded" && !data["superseded-by"])
+                add("error", file, "superseded without superseded-by");
+            const verified = asDate(data["last-verified"]);
+            const age = verified ? Math.floor((today.getTime() - verified.getTime()) / DAY_MS) : 0;
+            if (verified && age > STALE_AFTER_DAYS)
+                stale.push({ file, age });
+            if (data.id)
+                filesById.set(String(data.id), [...(filesById.get(String(data.id)) ?? []), file]);
+        }
+        // One line per product: hundreds of "page X is stale" lines bury every other finding.
+        if (stale.length > 0) {
+            const oldest = stale
+                .sort((a, b) => b.age - a.age)
+                .slice(0, OLDEST_SHOWN)
+                .map(({ file, age }) => `${file.replace(".context/wiki/", "")} (${age}d)`);
+            const pages = stale.length === 1 ? "1 page" : `${stale.length} pages`;
+            add("warn", ".context/wiki", `${pages} last verified over ${STALE_AFTER_DAYS} days ago — oldest: ${oldest.join(", ")}`);
+        }
+        for (const [id, files] of filesById) {
+            if (files.length > 1)
+                add("error", files[1], `duplicate id ${id} (also ${files[0]})`);
+        }
+        return findings;
+    },
+};

package/cli/dist/commands/add.js

@@ -0,0 +1,24 @@
+import { resolve } from "node:path";
+import { CACHE_DIR, fetchText, runCommand } from "../lib/system.js";
+import { addPack, fetchPackDocs, findPack, listPacks } from "../packs.js";
+import { requireEstate } from "./env.js";
+export function registerAdd(program, env) {
+    program
+        .command("add")
+        .description("add a knowledge pack (rules + vendor docs in search), e.g. zeno add expo")
+        .argument("[pack]", "pack name; omit to list packs")
+        .option("-g, --global", "add for every product (estate zeno.yaml)")
+        .option("--repo <repo>", "product repo", ".")
+        .action(async (name, options) => {
+        if (!name) {
+            for (const pack of listPacks(env.zenoRoot))
+                console.log(`${pack.name.padEnd(11)} ${pack.description}`);
+            return;
+        }
+        const estateRoot = options.global ? requireEstate(env) : undefined;
+        const { file, added } = addPack(resolve(options.repo), name, { zenoRoot: env.zenoRoot, global: options.global, estateRoot });
+        console.log(added ? `added ${name} to ${file}` : `${name} already in ${file}`);
+        const dir = await fetchPackDocs(findPack(env.zenoRoot, name), { cacheDir: CACHE_DIR, fetchText, run: runCommand });
+        console.log(`indexed ${dir} as qmd://pack-${name}`);
+    });
+}