baesian 0.0.0-stage → 1.0.0

package/LICENSE.md

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2026 Gus Ellerm
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/README.md

@@ -1,3 +1,218 @@
-# Temporary Holding Version
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/GusEllerm/baesian/main/docs/media/wordmark-dark.png">
+    <img src="https://raw.githubusercontent.com/GusEllerm/baesian/main/docs/media/wordmark.png" alt="Baesian" width="280">
+  </picture>
+</p>
 
-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.
+<p align="center"><b>Swipe review for the decisions your coding agents shouldn't make alone.</b><br>
+They put each one to you as a card, and you choose before you see their pick.</p>
+
+<p align="center">
+  <a href="https://baesian.dev">baesian.dev</a> ·
+  <a href="#try-the-demo">Try the demo</a> ·
+  <a href="#how-it-works">How it works</a> ·
+  <a href="#set-it-up">Set it up</a> ·
+  <a href="https://github.com/GusEllerm/baesian/blob/main/docs/setup.md">Setup guide</a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/GusEllerm/baesian/main/docs/media/demo.gif" width="74%" alt="Answering two agents' decision cards in Baesian: choose first, then see the agent's pick, while each agent's terminal gets the answer">
+  <img src="https://raw.githubusercontent.com/GusEllerm/baesian/main/docs/media/phone.png" width="22%" alt="A Baesian card held on a phone until it lifts, with its four answers named at the screen's edges">
+</p>
+<p align="center"><sub>At your desk, two agents building a made-up bakery's shop stop for you: you choose, see their pick,
+overrule one, and each agent's terminal gets your answer. On your phone, you hold a card until it lifts and drag it to
+an answer.</sub></p>
+
+Your Claude Code and Codex agents make design decisions all day, and a few of them are hard to undo: where a
+signed-in user's session lives, how prices are stored, what deleting an account removes. Baesian has the agent put
+those to you as cards, before it builds on them. You pick one of its two options before you see which it chose, then
+confirm or overrule it. Your answer goes back to the agent, and into git with the code it shapes.
+
+## Try the demo
+
+You need Node 22 or later, and git.
+
+```sh
+git clone https://github.com/GusEllerm/baesian.git
+cd baesian
+npm install
+npm run demo
+```
+
+The demo makes a throwaway repo where two agents are building Crumb, a made-up bakery's online shop, and have filed
+five decisions. It opens the client, and its terminal shows what each agent gets as you answer.
+
+## How it works
+
+1. **An agent files a card** when a decision is hard to undo or isn't its call alone: a schema, a public API, a
+   dependency, CI, security, anything user-facing. `baesian init` tells your agents when, in `AGENTS.md`.
+2. **You choose first,** between its two options, then see which it picked and why, and confirm or switch.
+3. **The agent waits as long as the decision needs:** on most cards it carries on and gets your answer at its next
+   pause; on a *blocking* card it waits for you; on a *hard* card, the default for security, privacy, data loss, money
+   and publishing, it never goes ahead without you, and you hold to confirm.
+4. **Your answer goes back to the agent,** and into git, committed with the code it shapes.
+
+Two things keep decisions from slipping past: a **commit gate** blocks a commit that adds a dependency, changes a
+schema or touches CI until a card covers it or the agent says why it's safe; and the **plugin** sends an agent that
+asks you to choose in chat back to file a card.
+
+## Why choose before you see the pick?
+
+Seeing the agent's case first anchors you: a confident argument is easy to agree with. Choosing first records, for
+each kind of decision, how often you'd have picked what the agent picked. That record is how Baesian suggests which
+kinds you could leave to the agent. When you keep answering one kind the same way, Baesian offers to make it a rule
+your agents follow without asking.
+
+## Decisions live in git
+
+Each branch carries its own cards, committed with its code, so decisions merge with the code they shaped. The client's
+**Your decisions, by branch** (press B) draws that history: where each branch began, what was decided on it, and every
+merge with what it brought.
+
+<p align="center"><img src="https://raw.githubusercontent.com/GusEllerm/baesian/main/docs/media/branches.png" width="100%" alt="Baesian's Branches drawer on its own history: merges and cards by branch, with one card opened to the three commits that cite it"></p>
+<p align="center"><sub>Baesian's own decisions on one evening: worktrees branching off v1/next, the cards filed on them
+and the commits citing those cards, merging back.</sub></p>
+
+Every commit names the cards it builds on, so if you change an answer later, the agent is told which commits built on
+the old one. In CI, `baesian verify` checks each commit's decisions, and holds a merge until its cards are answered.
+
+<p align="center"><img src="https://raw.githubusercontent.com/GusEllerm/baesian/main/docs/media/checkpoints.png" width="100%" alt="Four commits on feat/checkout, each carrying the decisions as they stood; when an answer later changes, the agent is told which commits built on the old one"></p>
+<p align="center"><sub>Each commit carries the decisions as they stood. When an answer changes, the commits that built on
+the old one are named.</sub></p>
+
+## Set it up
+
+You need Node 22 or later, git, and Claude Code or Codex. The
+[setup guide](https://github.com/GusEllerm/baesian/blob/main/docs/setup.md) has each step in full.
+
+### 1. Install the CLI
+
+```sh
+npm install -g baesian
+```
+
+### 2. Make an account
+
+Sign up at [baesian.dev](https://baesian.dev) and make a passkey. Add one on each device you answer from, your phone
+included.
+
+### 3. Set up your repo
+
+```sh
+cd your-repo
+baesian init
+baesian login
+```
+
+`init` sets up the commit gate and tells your agents about Baesian. `login` links the repo to baesian.dev: approve
+this machine on the page it prints, then run the commit it prints.
+
+### 4. Install the plugin
+
+In Claude Code:
+
+```text
+/plugin marketplace add GusEllerm/baesian
+/plugin install baesian@baesian
+```
+
+<details>
+<summary><b>Claude Code in VS Code, and Codex</b></summary>
+
+In the VS Code extension, run the same from a terminal, then start a new conversation:
+
+```sh
+claude plugin marketplace add GusEllerm/baesian
+claude plugin install baesian@baesian
+```
+
+In Codex:
+
+```sh
+codex plugin marketplace add GusEllerm/baesian
+codex plugin add baesian@baesian
+```
+
+Codex runs the plugin's hooks only after you accept its "Hooks need review" prompt in interactive mode, and again after
+any update.
+</details>
+
+<details>
+<summary><b>Updating</b></summary>
+
+Update the CLI and the plugin together, to the same release: `npm install -g baesian`, then
+`claude plugin update baesian@baesian` (in Codex, `codex plugin marketplace upgrade baesian`, then
+`codex plugin add baesian@baesian`). When they differ, the plugin tells your agent to ask you to update. Each release's
+notes say what else to run again; [the setup guide](https://github.com/GusEllerm/baesian/blob/main/docs/setup.md#updating)
+has the details.
+</details>
+
+<details>
+<summary><b>Checking decisions in CI</b></summary>
+
+```sh
+baesian ci --github
+```
+
+sets the repository variable CI reads its keys from: the service's, a spare it keeps offline, and your passkeys'. Then
+add the workflow steps it prints, which run the release that printed them until you run `baesian ci` again. See
+[the setup guide](https://github.com/GusEllerm/baesian/blob/main/docs/setup.md#5-check-decisions-in-ci).
+</details>
+
+<details>
+<summary><b>Without an account, or in a repo you share</b></summary>
+
+`baesian init` then `baesian serve` gives you the client on your own machine, with nothing sent anywhere; `baesian
+login` links the repo later. In a repo whose other contributors don't use Baesian, `baesian init --personal` keeps
+everything in your clone and commits nothing. Both are in
+[the setup guide](https://github.com/GusEllerm/baesian/blob/main/docs/setup.md#without-an-account).
+</details>
+
+## Releases
+
+Each release's notes, with anything to run again after updating, are on
+[GitHub Releases](https://github.com/GusEllerm/baesian/releases). From 1.0, every 1.x release reads the files earlier
+ones wrote, and keeps the hosted service's protocol and the commands, flags, exit codes and MCP tools your agents are
+told to use: the setup guide's [Compatibility](https://github.com/GusEllerm/baesian/blob/main/docs/setup.md#compatibility)
+section says how. To report a security problem, write to security@baesian.dev
+([SECURITY.md](https://github.com/GusEllerm/baesian/blob/main/SECURITY.md)).
+
+## Development
+
+To work on Baesian, build it from a clone and link it onto your PATH, in place of the `baesian` from npm:
+
+```sh
+git clone https://github.com/GusEllerm/baesian.git
+cd baesian
+npm install
+npm run build && npm link
+```
+
+To try the plugin from your clone, add its marketplace by path, `/plugin marketplace add /path/to/baesian`, then install
+it as above. Both marketplaces are named `baesian`, so remove the one from GitHub first:
+`/plugin marketplace remove baesian`.
+
+```sh
+npm test               # unit tests
+npm run e2e            # browser tests, with Playwright
+npm run typecheck
+npm run readme-media   # remakes this README's images (needs ffmpeg)
+```
+
+The project's memory is the Obsidian vault in
+[`docs/vault/`](https://github.com/GusEllerm/baesian/blob/main/docs/vault/Home.md): the design, the decision log, and a
+log of each working session. Start at `Home.md`.
+
+## Licence
+
+Baesian is source-available under the
+[Functional Source License 1.1](https://github.com/GusEllerm/baesian/blob/main/LICENSE.md) (FSL-1.1-ALv2): you may use, change
+and run it for any purpose except a product or service that competes with it, and each version becomes available under
+the Apache License 2.0 two years after its release.
+
+## Why "Baesian"
+
+It's a dating app for decisions. Your agents line up their options, you swipe on the one you'd pick before you see
+which one they picked, and over time you build up preferences for each kind of decision. The decisions you keep
+agreeing on become rules, so your agents can make them for you from then on.

package/dist/agents.js

@@ -0,0 +1,249 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { cite } from "./cite.js";
+// Tier 1 (D27): plain instructions any harness can read. `baesian init` keeps this block in AGENTS.md.
+export const BEGIN = "<!-- baesian:begin -->";
+export const END = "<!-- baesian:end -->";
+export const AGENTS_BLOCK = `${BEGIN}
+## Decisions (Baesian)
+
+Design decisions that are hard to undo go to a person as cards; you don't make them silently. Run
+\`baesian inbox\` before starting work, and again when you finish a task: it shows new verdicts on this branch's
+cards, to act on then rather than mid-task.
+
+**File a card** (\`baesian template > card.md\`, fill it in, \`baesian file card.md\`) when a decision
+changes a schema or on-disk format; changes a public API, URL scheme or module boundary; adds a runtime
+dependency; changes CI, infrastructure or deployment; is user-facing; publishes something; touches
+security or privacy; spends money; deletes or overwrites stored data; or would break something to
+reverse. Otherwise decide yourself. Every card states its strongest alternative, and the one question
+the choice turns on (the crux). A topic names one question: reuse one from \`baesian topics\` only for the
+same question, and give a follow-on question its own, narrower topic. The reviewer chooses before seeing
+your pick, your case or the card's body; put what they need in order to choose, kept neutral, in
+\`crux_fact\`, and background in the body. Make your case in \`rationale\`, and the alternative's best case
+in \`alternative_rationale\`, as you'd argue it if it were your pick. The decision record is committed
+with the code, so don't paste secrets, credentials or private output into a card.
+
+A choice you'd put to the reviewer in chat goes as a card, even when they're in the conversation: say
+"it's in your deck" and don't list the options there, so they still choose before seeing your pick. A
+choice the reviewer has already answered in chat is filed all the same, with their answer as your pick and
+their words in \`answered_in_chat\`, for them to confirm with one tap; otherwise, file it before you ask. A
+change that only restores what a card or rule decided cites it, and needs no card.
+
+**The commit gate** detects some of these decisions (dependencies, schemas and migrations, CI and
+deploy files) and blocks a commit until each one is covered. Either cite a card whose \`touches\`
+include it, \`Baesian-Card: <id>\`, or, for a two-way door, acknowledge it with a reason:
+\`Baesian-Ack: dep:httpx <why this is fine>\`. When it blocks, the gate prints the lines to paste.
+\`baesian check\` previews it before you commit. Trailers go at the end of the message, after a blank
+line.
+
+- \`level: provisional\` (the default): carry on with your proposal. \`blocking\`: run \`baesian wait <id>\`
+  before building on it. \`hard\` (the default for publishing, security, privacy, money and data loss): never
+  proceed without a verdict. A level is a minimum only when the card is shown: the repo's preferences may
+  hold a card back instead, and \`baesian file\` says so. A held card means go ahead with your pick, as
+  provisional, citing it as usual; it counts as settled at merge, and the reviewer may answer it later.
+- \`baesian wait <id>\` exits 0 when resolved (use the decision. If it went against your pick and you hold
+  a fact the reviewer lacked, or a check that would settle it, you may reply once:
+  \`baesian reply <id> "<the fact or check>"\`. Not your pick again); 4 when answered otherwise (returned:
+  read the comment, then \`baesian revise <id>\` or \`baesian withdraw <id>\`); 5 with no verdict yet
+  (proceed provisionally); 6 with no verdict on a hard card (don't proceed: park the task or stop); 7 while
+  the reviewer is still there (run \`baesian wait <id>\` again); 8 when the card is held back (go ahead with
+  your pick, as provisional). Each run lasts at most 100 seconds.
+- If you end your turn with cards still with the reviewer whose answers you'll act on (blocking or hard
+  ones, or provisional ones), and your harness wakes you when a background command finishes (Claude Code
+  does), leave \`baesian wait <id> <id>… --until-answered\` running in the background, or \`--deck <deck>\`
+  for your open cards in a deck. It has no time limit: it ends when every card is answered (0 when all are
+  resolved, else 4), or sooner when one is returned (4) or held back (8). When it ends, act on the answers
+  it printed; \`baesian inbox\` won't repeat them. Without that (Codex), answers come with the next message.
+- If an answer asks for a rule (\`wait\` and \`inbox\` say so), draft it, with the gate patterns it covers:
+  \`baesian rule <id> "<the rule>" --covers dep:pytest-*\`. It goes to the reviewer as a card.
+- If you're a long-lived agent, set \`BAESIAN_AGENT\` to your name; otherwise your harness's name is used.
+- If \`baesian file\` exits 3, the decision may already be open or decided: attach with
+  \`baesian attach <id>\`, or follow the decision. File with \`--new\` only to argue against one, and set
+  \`supersedes:\`. If yours is a different question on the same subject, give it a narrower topic
+  (\`client/rule-drafts\` beside \`client/rules\`) and list what it builds on in \`depends_on\`.
+- Commits that build on a card carry the trailer \`Baesian-Card: <id>\`. The gate blocks a commit that
+  builds on a rejected card, or on a hard card that isn't resolved yet.
+- Never record a verdict yourself, or write the repo's preference files: only a person answers, and sets
+  the preferences, in the Baesian client.
+${END}`;
+/**
+ * Who is running a command (D102): `--agent`, then `$BAESIAN_AGENT` (a long-lived agent's own name), then the
+ * name the harness gives itself, then "agent". The MCP server passes the name its client gave in the protocol, which
+ * comes before the harness's variables, since a stdio server isn't given them all (P18).
+ */
+export function agentName(opt, env = process.env, client) {
+    return opt ?? (env.BAESIAN_AGENT?.trim() || undefined) ?? clientAgentName(client) ?? harnessName(env) ?? "agent";
+}
+/** An MCP client's name as an agent's: Claude Code's and Codex's become the names their commands get; others stay. */
+export function clientAgentName(client) {
+    const name = client?.trim();
+    if (!name)
+        return undefined;
+    if (/^claude[-_ ]?code\b/i.test(name))
+        return "claude-code";
+    if (/^codex\b/i.test(name))
+        return "codex";
+    return name;
+}
+/** The harness's own name, from the variables it sets for the commands it runs. */
+/**
+ * The harness session a command runs in, when the harness says: Claude Code gives its commands
+ * `CLAUDE_CODE_SESSION_ID`, and Codex `CODEX_THREAD_ID`, each the same ID its hooks receive as `session_id`. So an
+ * agent's own `baesian inbox` reads its session's place, as the plugin's hooks do (B-ghhym), and never hears twice.
+ */
+export function harnessSession(env = process.env) {
+    return env.CLAUDE_CODE_SESSION_ID?.trim() || env.CODEX_THREAD_ID?.trim() || undefined;
+}
+/**
+ * The sessions a command's model is looked up by (B-k0w7d), in order: Claude Code's `CLAUDE_CODE_SESSION_ID`; and in
+ * Codex `CODEX_SESSION_ID`, which Codex's source names but which wasn't seen set, then `CODEX_THREAD_ID`, which rehearse
+ * found equal to the hooks' `session_id` in Codex 0.166.0. Codex's source fills the hooks' `session_id` from the session
+ * and the variable from the thread, so in a thread of its own (a subagent's, say) they may differ: then no file
+ * matches, and the card has no model rather than a wrong one.
+ */
+export function modelSessions(env = process.env) {
+    const ids = [env.CLAUDE_CODE_SESSION_ID, env.CODEX_SESSION_ID, env.CODEX_THREAD_ID].map((v) => v?.trim()).filter((v) => Boolean(v));
+    return [...new Set(ids)];
+}
+export function harnessName(env) {
+    // Claude Code sets AI_AGENT to "<name>_<version>_<role>", for example "claude-code_2-1-314_agent".
+    const ai = env.AI_AGENT?.trim();
+    if (ai)
+        return ai.split("_")[0] || undefined;
+    if (env.CLAUDE_CODE_ENTRYPOINT || env.CLAUDECODE)
+        return "claude-code";
+    // Codex sets no AI_AGENT, but gives the commands it runs a per-session CODEX_THREAD_ID (seen in 0.166.0, by
+    // rehearse's agent, with no model calls).
+    if (env.CODEX_THREAD_ID)
+        return "codex";
+    return undefined;
+}
+/**
+ * The block for a repo, with its vault's guidance (M6, D173): with a vault, one sentence points agents to its routing
+ * notes and its rules, to read when deciding whether to file. They're guidance: the gate takes rules only from the store.
+ */
+export function agentsBlock(vault) {
+    if (!vault)
+        return AGENTS_BLOCK;
+    const read = [...vault.notes.map((n) => `\`${n}\``), `the rules in force, in \`${vault.rules}\``];
+    const sentence = `Before deciding whether to file, read this repo's guidance in its vault: ${read.length > 2 ? `${read.slice(0, -1).join(", ")} and ${read.at(-1)}` : read.join(" and ")}.`;
+    return AGENTS_BLOCK.replace("\n\n**The commit gate**", `\n\n${sentence}\n\n**The commit gate**`);
+}
+/** Write or refresh the Baesian block in `AGENTS.md`, leaving everything outside the markers alone. */
+export function writeAgentsBlock(toplevel, vault) {
+    const path = join(toplevel, "AGENTS.md");
+    const block = agentsBlock(vault);
+    if (!existsSync(path)) {
+        writeFileSync(path, `# Agent instructions\n\n${block}\n`);
+        return "created";
+    }
+    const text = readFileSync(path, "utf8");
+    const start = text.indexOf(BEGIN);
+    const end = text.indexOf(END);
+    if (start < 0 || end < start) {
+        writeFileSync(path, `${text.replace(/\s*$/, "")}\n\n${block}\n`);
+        return "appended";
+    }
+    const next = text.slice(0, start) + block + text.slice(end + END.length);
+    if (next === text)
+        return "unchanged";
+    writeFileSync(path, next);
+    return "updated";
+}
+/** In personal mode, what the block says about the record, which isn't committed there. */
+const RECORD_SENTENCE = "The decision record is committed\nwith the code, so don't paste secrets, credentials or private output into a card.";
+/**
+ * What an agent is told in a clone that uses Baesian in personal mode (B-4rwyz), where AGENTS.md says nothing of it: the
+ * plugin's session-start hook hands it over once a session (`baesian inbox --quiet`). It's `AGENTS_BLOCK`'s instructions,
+ * after a paragraph on what personal mode changes for the agent.
+ */
+export function personalInstructions() {
+    const body = AGENTS_BLOCK.slice(BEGIN.length, -END.length).trim();
+    if (!body.includes(RECORD_SENTENCE))
+        throw new Error("AGENTS_BLOCK no longer says the record is committed in the words personal mode replaces");
+    return [
+        `Baesian, in personal mode${cite("B-4rwyz")}: this clone uses Baesian for the person you're working with, and the repo's`,
+        "collaborators don't, so AGENTS.md doesn't mention it and nothing of Baesian's is committed. Its instructions still apply",
+        "to you, as below. The commit gate checks your commits as usual, and takes `Baesian-Card` and `Baesian-Ack` trailers out",
+        "of the message once it has, into this clone's ledger. Keep card IDs and Baesian itself out of anything others see: code,",
+        "comments, commit messages, pull requests. `baesian inbox` says when this clone's setup needs fixing.",
+        "",
+        body.replace(RECORD_SENTENCE, "The decision record stays in this\nclone, but a card reaches the reviewer's website in a linked repo, so don't paste secrets, credentials\nor private output into a card."),
+    ].join("\n");
+}
+/** Claude Code reads CLAUDE.md, not AGENTS.md. Warn when CLAUDE.md exists and doesn't import it. */
+export function claudeMdMissesAgents(toplevel) {
+    const path = join(toplevel, "CLAUDE.md");
+    return existsSync(path) && !/@AGENTS\.md/.test(readFileSync(path, "utf8"));
+}
+/**
+ * The card's fields, with their notes, in the template's order: one table, so `baesian template` and the MCP filing
+ * tool's schema can't drift apart (D167).
+ */
+export const CARD_FIELDS = [
+    { field: "title", value: '""', note: 'a neutral short name: "Where the access token lives"' },
+    { field: "question", value: '""', note: "the decision, as a neutral question" },
+    { field: "doing", value: '""', note: "what you were doing when it came up: \"writing the server's file watcher\"" },
+    { field: "topic", value: '""', note: "area/subject, naming this one question; reuse one from `baesian topics` only for the same question" },
+    { field: "touches", value: "[]", note: "any of: schema, public-api, dependency, infra, user-facing, publishes, security, privacy, money, data-loss" },
+    { field: "reverse", value: '""', note: "how costly it is to undo: cheap, moderate or one-way" },
+    { field: "proposal", value: '""', note: "your pick, in a few words" },
+    { field: "proposal_then", value: '""', note: "what happens if it's chosen, read after \"then\": \"the relay keeps…\"" },
+    { field: "alternative", value: '""', note: "the strongest alternative, in a few words" },
+    { field: "alternative_then", value: '""', note: "what happens if it's chosen, read after \"then\"" },
+    { field: "crux", value: '""', note: "the one question the choice turns on" },
+    { field: "crux_proposal", value: '""', note: 'the answer that leads to your pick: "If it does"' },
+    { field: "crux_alternative", value: '""', note: "the answer that leads to the alternative: \"If it doesn't\"" },
+    { field: "crux_preference", value: "true", optional: true, note: "the crux is about what the reviewer values, not a fact" },
+    { field: "crux_fact", value: '""', optional: true, note: "what the reviewer needs to choose, kept neutral: the only context they see first" },
+    { field: "rationale", value: '""', optional: true, note: "why you pick the proposal" },
+    { field: "alternative_rationale", value: '""', optional: true, note: "the best case for the alternative: why you'd pick it, if it were your pick" },
+    {
+        field: "answered_in_chat", value: '""', optional: true,
+        note: "only if the reviewer already answered it in chat: what they said, quoted and short; your pick is their answer, which they confirm with one tap",
+    },
+    {
+        field: "wrong_if", value: '""', optional: true,
+        note: "what would show your pick is wrong: required if reverse is one-way, touches includes security or privacy, or a premise is set",
+        line: "(what would show your pick is wrong: required if reverse is one-way,",
+    },
+    {
+        field: "check", value: '""', optional: true,
+        note: "where to look to check wrong_if: required with it",
+        line: " touches includes security or privacy, or a premise is set; check says where to look)",
+    },
+    { field: "premise", value: '""', optional: true, note: "a claim an option rests on that nobody has checked; give premise_option and premise_check with it", line: "(a claim an option rests on that nobody has checked," },
+    { field: "premise_option", value: "proposal", optional: true, note: "which option the premise rests on: proposal or alternative", line: " which option rests on it," },
+    { field: "premise_check", value: '""', optional: true, note: "how to check the premise", line: " and how to check it)" },
+    { field: "acted", value: '""', optional: true, note: "what you've already built for one option; give acted_option with it", line: "(what you've already built for one option," },
+    { field: "acted_option", value: "proposal", optional: true, note: "which option you've already built for: proposal or alternative", line: " and which)" },
+    { field: "serves", value: '""', optional: true, note: "the criterion your pick serves, when the crux is a preference" },
+    { field: "also_considered", value: "[]", optional: true, note: "other options, by name" },
+    { field: "rules", value: "[R-xxxxx]", optional: true, note: "rules this decision bears on" },
+    { field: "proposal_breaks", value: "[]", optional: true, note: "decisions or rules your pick would replace or break" },
+    { field: "alternative_breaks", value: "[]", optional: true, note: "decisions or rules the alternative would replace or break", line: "" },
+    { field: "level", value: "blocking", optional: true, note: "provisional by default; hard by default for publishes, security, privacy, money, data-loss; a minimum only if the card is shown" },
+    { field: "depends_on", value: "[B-xxxxx]", optional: true, note: "the cards this decision builds on", line: "" },
+    { field: "deck", value: "storage-layer", optional: true, note: "your branch's deck by default" },
+    { field: "supersedes", value: "", template: false, note: "a decision this card argues against, filed with new; it becomes superseded once this card resolves" },
+    { field: "modules_touched", value: "", template: false, note: "how many modules the decision touches" },
+    { field: "confidence", value: "", template: false, note: "your confidence in your pick, from 0 to 1: recorded, not used for routing" },
+    { field: "domain", value: "", template: false, note: "routing tags" },
+    { field: "evidence", value: "", template: false, note: "links that bear on the decision" },
+    {
+        field: "secret_reason", value: "", template: false,
+        note: "why you file a card that looks like it holds a secret: in a hosted repo filing refuses one without it (B-jfkv9). Kept on the card, where reviewers see it",
+    },
+];
+function templateLine(f) {
+    const head = f.optional ? `# ${f.field}: ${f.value}` : `${f.field}: ${f.value}`;
+    const comment = f.line ?? (f.optional ? `(${f.note})` : `# ${f.note}`);
+    // The comments start in one column, and a field too long for it keeps a space before its own.
+    return comment ? `${head.padEnd((f.optional ? 27 : 23) - 1)} ${comment}` : head;
+}
+export const CARD_TEMPLATE = `---
+${CARD_FIELDS.filter((f) => f.template !== false).map(templateLine).join("\n")}
+# Below the closing line, optionally: background, shown with your case once the reviewer has chosen.
+---
+`;
+//# sourceMappingURL=agents.js.map

package/dist/api.js

@@ -0,0 +1,13 @@
+/** The fields a verdict may be sent with (`ApiVerdictInput`); anything else is refused. The local server and the relay share them. */
+export const VERDICT_FIELDS = new Set(["card", "revision", "response", "choice", "comment", "first_choice", "make_rule", "retire_rules", "should_have_asked"]);
+/** The fields a preference change may be sent with (`ApiPreferencesInput`); anything else is refused. */
+export const PREFERENCE_FIELDS = new Set([
+    "replaces", "preset", "mode", "rate_agent_decides", "rate_sample", "burn_in", "reason", "survey_see", "survey_fine",
+    "gate_schema", "gate_infra", "gate_api", "gate_ignore",
+    ...["public_api", "schema", "dependency", "infra", "user_facing", "security", "privacy", "other"].map((r) => `row_${r}`),
+]);
+/** The fields a practice entry may be sent with (`ApiPracticeInput`); anything else is refused. The local server and the relay share them. */
+export const PRACTICE_FIELDS = new Set(["kind", "card", "revision", "answered", "blind", "final", "test", "mark", "practice"]);
+/** The milliseconds after which a waiting marker counts as gone; the same as the store's. */
+export const WAITING_STALE_MS = 90_000;
+//# sourceMappingURL=api.js.map

package/dist/bin.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { main } from "./cli.js";
+// A reader that stops early (`baesian show B-x | head -1`) closes the pipe it reads: what's left to write has nowhere to
+// go, so the command ends there, quietly, as a shell's own tools do, rather than with Node's unhandled EPIPE. Any other
+// failure to write is still one.
+for (const stream of [process.stdout, process.stderr]) {
+    stream.on("error", (e) => {
+        if (e.code === "EPIPE")
+            process.exit(0);
+        throw e;
+    });
+}
+process.exitCode = await main();
+//# sourceMappingURL=bin.js.map