.ai/BRIEF.md

<!--
GENERATED FILE - DO NOT EDIT BY HAND.
Generated by `skills/everything/scripts/build_brief.py`. Edit the sources, then regenerate.
This is what a new session reads. The corpus behind it is unbounded;
this file is capped, and items compete for a place in it on value.
-->

# Brief

_Budget: standard tier, 12,000 tokens. Anything that did not fit is listed as a pointer at the end - demoted, not dropped._

## What this system is

Akinator - the knowledge-layer operating system for AI-maintained codebases.
**One skill, one command, on every platform**: `/akinator:everything` on Claude
Code, `$akinator` on Codex, `/akinator` on Cursor - and normally none at all,
because it is always on. Installed into a repository, it makes it structurally
impossible to change code without growing the knowledge around it.

**This repo is maintained under its own discipline.** Every change here carries
its own docs, skills, rules, context and memory delta.

## Constraints that must not break

- **Rule 01 - Every batch declares and delivers a knowledge delta** - Documentation does not get skipped by decision. It gets skipped because it never became a line item, so nobody ever noticed its absence. The fix is structural: the knowledge delta is **named at plan time, by path**, before any code exists....
  `rules/01-knowledge-delta-per-batch.md`
- **Rule 02 - Every skill carries all six parts** - A skill missing a part fails in a specific, predictable way:
  `rules/02-skills-carry-all-six-parts.md`
- **Rule 03 - Every rule names an enforcement mechanism that exists** - A constraint written as prose and enforced by nothing is not a rule. It is a hope, and it will be broken within a quarter by a well-meaning contributor whose review is done by someone who was not in the original conversation.
  `rules/03-rules-need-live-enforcement.md`
- **Rule 04 - Routers stay thin, and they never fork** - Every AI tool reads a different entry file. Each one that gets updated alone becomes a separate version of the truth, and an agent reading the stale one acts confidently and wrongly - which is the most expensive failure mode available, beca...
  `rules/04-routers-stay-thin-and-synced.md`
- **Rule 05 - Never put knowledge checks in git hooks** - Git hooks gate **code**, and they must stay fast. A pre-commit hook that also runs documentation checks, coverage audits, index verification or router-sync validation produces three failures, in this order:
  `rules/05-no-git-hook-complication.md`
- **Rule 06 - Gate once, at the end, scoped to what was touched** - Running the full lint, typecheck, test and build loop after every change is the most expensive habit available. It proves the same thing repeatedly while the tree keeps changing underneath it, and on a loaded machine it produces timeout fla...
  `rules/06-gate-once-scoped-at-the-end.md`
- **Rule 07 - The Codex pack is generated, never hand-edited** - Akinator ships the same behavioral contract to two platforms. If both copies are maintained by hand they will diverge, and the divergence will be invisible: the Claude user and the Codex user will each believe they are running the same plug...
  `rules/07-codex-pack-is-generated.md`
- **Rule 08 - `skills/` holds only skill directories** - Both plugin platforms import skills by scanning `skills/` for **subdirectories containing `SKILL.md`**. A loose file directly under `skills/` is not imported - and Codex plugin validation rejects the plugin outright with:
  `rules/08-skills-dir-holds-only-skill-directories.md`
- **Rule 09 - Every router is rendered from one contract** - Every AI tool reads a different entry file. This repository ships eleven of them - Claude, Codex, Gemini, GLM, Kimi, Qwen, DeepSeek, Mistral, Cursor, Copilot and the common `AGENTS.md` fallback.
  `rules/09-routers-are-rendered-from-one-contract.md`
- **Rule 10 - Ledger records are redacted before they are written** - The ledger exists to capture what broke. What broke arrives as **error text**, and error text carries credentials: bearer tokens in a failed request, a connection string in a database error, an API key echoed by a misconfigured client, a cu...
  `rules/10-ledger-records-are-redacted-before-write.md`
- **Rule 11 - Every invariant ships with a test that proves it fires** - A checker cannot be validated by running it on a healthy tree and seeing zero findings. **Zero findings is exactly what a broken checker produces.**
  `rules/11-invariants-ship-with-a-mutation-test.md`
- **Rule 12 - An artifact that travels names nothing only its birthplace has** - Akinator's whole premise is that a document asserting things that are not there is a critical defect. It was shipping 22 of them per install.
  `rules/12-artifacts-that-travel-name-nothing-local.md`
- **Rule 13 - Every prompt is documented everywhere it lands** - A repository that is "exhaustively documented" as of the last audit and silent about the last ten prompts is not exhaustively documented - it is a snapshot with a caption that lied the moment work resumed. The owner's requirement is corpora...
  `rules/13-every-prompt-is-documented.md`

## Recurring failures and their fixes

- **a generated artifact that travels named files only its birthplace has (seen 3x)** - **Symptom:** a bare repository that installs the Codex pack fails the coverage checker on its first run with 22 HIGH findings, every one on a file the plugin just wrote **Fix:** both banners name no file at all; they state the origin and how to refresh instead. check_generated grew a vendored branch requiring both halves, and the pack is now checked from a...
  `.ai/ledger/failure/a-generated-artifact-that-travels-named-56871dcd648a.md`
- **a coverage check reported green because its matcher was too loose (seen 3x)** - **Symptom:** the checker exits 0 and the report says all invariants hold, on a tree that violates one **Fix:** resolve each index reference to a repo-relative path and compare; never pattern-match a bare token
  `.ai/ledger/failure/checker-silent-false-negative-a1b2c3d4e5f6.md`
- **backslash escapes collapsed inside a shell heredoc and silently changed a regex (seen 4x)** - **Symptom:** a regex written as \b...\b reached the file as a literal backspace character, so the pattern compiled and matched nothing; the check it guarded passed by never firing **Fix:** write anything containing a backslash with the Edit or Write tool, never through a heredoc; if a shell is unavoidable, build the escape with chr(92) rather than typing it
  `.ai/ledger/failure/heredoc-ate-the-backslashes-7f3a91c204de.md`
- **a fact was corrected everywhere except the index that states it (seen 2x)** - **Symptom:** a doc says 21 and links to a page that says twenty; the reader clicks through from a corrected number to an uncorrected one **Fix:** grep for the fact, not for the artifact that holds it; a router carries facts, not only links
  `.ai/ledger/failure/fixed-pointers-left-the-index-b2c3d4e5f6a7.md`
- **an edit to a skill dropped part of its required six-part contract (seen 2x)** - **Symptom:** the skill-format check failed after skill descriptions were rewritten: one lost its 'Use when' trigger phrasing, another lost its 'When NOT to use' section **Fix:** restored the 'Use when' lead in akinator's description (b48f15f) and the 'When NOT to use' section in akinator-everything (e62bf87); neither repair was recorded at the time, which...
  `.ai/ledger/failure/skill-edit-dropped-its-contract-4c1e8a92b7d3.md`
- **an ADR was filed under a number another ADR already held (seen 1x)** - **Symptom:** two files named docs/adr/0006-*.md, and a loose bullet under the ADR index table instead of a row **Fix:** the newer record moved to 0008, the index got a proper row, and tests/test_plugin_structure.py::test_adr_numbers_are_unique now fails on any reused number (mutation-tested)
  `.ai/ledger/failure/adr-number-filed-twice-5c0e93b8a14d.md`
- **a hand-made logo failed CI after seven minutes of printing a PNG byte diff (seen 1x)** - **Symptom:** every CI run on main failed from the logo commit onward, each taking about seven minutes instead of twenty seconds **Fix:** the generator and that test were retired, as the deviation entry prescribed; test_required_asset_is_a_square_png keeps the part Codex actually requires
  `.ai/ledger/failure/byte-compare-test-hid-a-logo-for-7-minutes-e1b6f3a09d27.md`
- **a generator emitted a reference to a path the same batch deleted (seen 1x)** - **Symptom:** every rendered router pointed at a command file the rename had just removed **Fix:** after any rename, grep the generators too, then re-run the drift check - which is what caught it
  `.ai/ledger/failure/generator-emitted-a-dead-reference-c3d4e5f6a7b8.md`
- **the SessionStart hook exited 126 on the Claude Code CLI, so always-on silently never started (seen 1x)** - **Symptom:** Akinator behaved as if absent in terminal sessions on Windows - no contract in context - while the VS Code extension worked; the hook outcome was error, exit 126, stderr '/usr/bin/... **Fix:** exec form: command 'sh', args ['${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh']. Verified live on 2.1.154 from a stream-json session: hook_response exit_code 0, outcome success. The...
  `.ai/ledger/failure/hook-shell-form-exited-126-8b21c6e0d4f3.md`
- **the installer rewrote a CRLF AGENTS.md as LF, so uninstall could not restore it (seen 1x)** - **Symptom:** after install and uninstall a host repository's AGENTS.md differed from the original byte for byte, though it looked identical **Fix:** both installers detect CRLF, edit in LF, and convert back before writing. Caught before shipping by the byte-for-byte uninstall test in tests/test_installer.py, which runs on Windo...
  `.ai/ledger/failure/installer-rewrote-line-endings-d7e4a1f09c62.md`
- **one command file still showed twenty-two entries in the slash menu (seen 1x)** - **Symptom:** typing /akinator in Claude Code listed /akinator:everything plus twenty-one /akinator:akinator-* entries, against the owner's explicit, repeated requirement of exactly one command **Fix:** one skill: the twenty-one skills became station references inside skills/everything/, which is also the command, and commands/ was removed. Proven from the live init event of a 2.1...
  `.ai/ledger/failure/slash-menu-listed-every-skill-3f9a0c71e2b5.md`

## Business rules with numbers

_nothing recorded yet_

## Requirements - current, changed and missing

- **Listing refreshed for the living-wiki release (missing)** - The plugin-directory listing mentions the living wiki, the 15-question budget and akinator-decide/akinator-wiki. **Source:** owner, 2026-09-18/19 sessions
  `.ai/ledger/requirement/listing-refreshed-for-the-living-wiki-release.md`
- **Live verification of Codex and Cursor routes (missing)** - Codex and Cursor install/run routes are confirmed live, not only from docs and source. **Source:** owner, 2026-09-18/19 sessions
  `.ai/ledger/requirement/live-verification-of-codex-and-cursor-routes.md`
- **Quantified AI-cost-reduction figure (missing)** - A measured dollar or token figure backs the AI-cost-reduction claim (capped brief, generated facts). **Source:** owner, 2026-09-18/19 sessions
  `.ai/ledger/requirement/quantified-ai-cost-reduction-figure.md`
- **Stated revenue or pricing model (missing)** - A revenue or pricing model beyond free/MIT is stated. **Source:** owner, 2026-09-18/19 sessions
  `.ai/ledger/requirement/stated-revenue-or-pricing-model.md`
- **Always on, no command normally typed (current)** - Akinator is always on; normal prompts require no command. **Source:** owner, 2026-09-18/19 sessions
  `.ai/ledger/requirement/always-on-no-command-normally-typed.md`
- **Every prompt documented everywhere it lands (current)** - Every prompt and every change is documented, product to project, so any AI reading the repository knows it. **Source:** owner, 2026-09-18/19 sessions
  `.ai/ledger/requirement/every-prompt-documented-everywhere-it-lands.md`
- **Generated facts, curated why, honest gaps (current)** - Facts are generated and cannot rot; why is curated and preserved; unknowns are marked honestly rather than filled with filler. **Source:** owner, 2026-09-18/19 sessions
  `.ai/ledger/requirement/generated-facts-curated-why-honest-gaps.md`
- **Many questions with recommended defaults (current)** - Many questions per prompt, grouped and ranked in one message, each with a recommended default. **Source:** owner, 2026-09-18/19 sessions
  `.ai/ledger/requirement/many-questions-with-recommended-defaults.md`
- **One-line install with no marketplace (current)** - Install in one line, with no marketplace required. **Source:** owner, 2026-09-18/19 sessions
  `.ai/ledger/requirement/one-line-install-with-no-marketplace.md`
- **One skill, one command on every platform (current)** - Exactly one skill and one command surface on every platform - /akinator:everything (Claude Code), $akinator (Codex), /akinator (Cursor). **Source:** owner, 2026-09-18/19 sessions
  `.ai/ledger/requirement/one-skill-one-command-on-every-platform.md`
- **Tools travel with the skill (current)** - Host-repo tools travel with the skill; nothing installed elsewhere names a path that exists only in this checkout. **Source:** owner, 2026-09-18/19 sessions
  `.ai/ledger/requirement/tools-travel-with-the-skill.md`

## Business and product drift

- **Generated logo replaced by hand-designed artwork (business)** - **Before:** A generated logo, produced by a script in the repository **After:** Hand-designed 1254x1254 artwork; the generator script removed **Why:** The owner replaced the generated mark with commissioned artwork; a later byte-compare CI test against it then failed on every run until remo...
  `.ai/ledger/drift/generated-logo-replaced-by-hand-designed-artwork.md`
- **No document per library becomes a generated page per library (requirement)** - **Before:** The stack map explicitly refused a page per dependency, because a page restating package.json rots **After:** A generated page per dependency under docs/wiki/libraries/, facts regenerated between markers, curated sections preserved **Why:** The owner's corporate-scale requirement includes libraries and why they were chosen; generated/curated split answers the original rot object...
  `.ai/ledger/drift/no-document-per-library-becomes-a-generated-page-per-library.md`
- **Question budget raised from five to fifteen (product)** - **Before:** Five-question interrupt budget per session (docs/scoping.md) **After:** Up to fifteen questions per prompt, grouped and ranked, each with a recommended default **Why:** Corporate-scale knowledge needs many answers captured; ranking, grouping and defaults fix interrupt fatigue instead of a low cap that leaves...
  `.ai/ledger/drift/question-budget-raised-from-five-to-fifteen.md`
- **Six commands collapsed to one command (scope)** - **Before:** Six planned commands: onboard, audit, status, sync, question, decide (build brief Part 9) **After:** One command, /akinator:everything, with mode dispatch by argument **Why:** Owner stated directly: only one command should do everything.
  `.ai/ledger/drift/six-commands-collapsed-to-one-command.md`
- **Command file replaced by one skill as the command (architecture)** - **Before:** One command file plus twenty separate station skills still listed individually in the menu **After:** One skill (skills/everything/) whose stations are references, opened on demand; the skill is the command **Why:** A live Claude Code session showed 22 entries in the / menu, not one; Codex and Cursor cannot hide a skill from their pickers at all.
  `.ai/ledger/drift/command-file-replaced-by-one-skill-as-the-command.md`

## Open questions blocking work

- **How large should the context brief be?** - **Answered:** Larger than the initial 4k proposal. Standard tier is 12,000 tokens, with lean 4k and deep 25k. At 12k the brief carries the constraint set and the recurring-failure catalogue as content rather than one-line pointers, an
  `.ai/ledger/question/how-big-should-the-brief-budget-be.md`
- **Where should the failure signal come from?** - **Answered:** All three, cross-referenced. Self-report is the rich signal - the only source carrying the trigger and the misleading symptom. Git and CI are the honesty check: a fix: commit with no self-reported failure is itself a fin
  `.ai/ledger/question/where-does-the-failure-signal-come-from.md`

## Where to look for what

- **Constraints you must not break** - 
  `rules/README.md`
- **How to do things here** - 
  `docs/skills.md`
- **Architecture, decisions, compatibility** - 
  `docs/README.md`
- **What happened, and what recurs** - 
  `docs/ledger.md`
- **Structural facts, generated** - 
  `context/README.md`
- **Durable decisions and surprises** - 
  `memory/index.md`
- **Review lenses and what each vetoes** - 
  `docs/agents.md`
- **What gets written into target repos** - 
  `templates/README.md`