@abaigram/abaikit 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joon Hwa Jung
+
+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,16 @@
-# Temporary Holding Version
+# @abaigram/abaikit
 
-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.
+The abai authoring tool, itself an abaigram. A coding agent uses it to
+make a program an abaigram under the contract, `spec/abaigrammar.md` in
+the [abai repository](https://github.com/jjbits/abai). Installed with
+`npm install --save-dev @abaigram/abaikit`, the command is `abaikit`.
+
+- `abaikit learnabai` prints the guide the agent follows; `--skill`
+  installs it as a Claude Code skill.
+- `abaikit check <repo>` verifies a repository's conformance and its
+  level; it needs no model.
+- `abaikit new <name> --lang ts` creates a fresh abaigram.
+- `abaikit abaify <repo>` retrofits an existing repository, adding and
+  never removing.
+- `abaikit run <repo> -- ARGS` starts the repository's program.
+- `abaikit abai ...` is the standard agent entry of abaikit itself.

package/abai/identity.md

@@ -0,0 +1 @@
+You are the agent fused into abaikit, the abai authoring tool. You help a person create an abaigram, retrofit an existing repository into one, and verify conformance. You change a repository only through the repo.* capabilities, which add and never remove; you say why in every act; and you run check before you call anything done.

package/abai/learnabai.md

@@ -0,0 +1,546 @@
+# learnabai: abai for a coding agent
+
+abaigrammar {{abaigrammar}} · abai stub {{stub}} · abaikit {{abaikit}} · TypeScript
+
+You are reading this because someone wants a program turned into an
+abaigram, or a new one made, and you are the agent doing it. Read section
+1 once. Follow section 5 step by step; every step ends in a command that
+proves it. Keep sections 2 and 8 at hand while you edit. `abaikit
+learnabai --section <id>` prints one section; the ids are in the headings.
+
+## 1. What an abaigram is (what)
+
+An abaigram is an ordinary program that includes the abai library (the
+"stub") and thereby carries an agent: the agent ships with the program,
+can run at install and during use, and observes and steers the program
+only through channels the program declares. The contract is
+`abaigrammar.md`; this guide is its TypeScript instantiation in practice.
+
+Two halves, one boundary. The stub lives in the program. The harness is
+the agent's runtime: a model, a tool set, a user channel. The boundary is
+a function call inside the process (turns and thread modes) or a local
+socket between two processes (sidecar mode). It means the same thing
+either way.
+
+Five channels, declared in a manifest the program builds in code:
+
+- `events`: the program tells the agent something happened (push).
+- `cells`: shared state the agent reads; a writable cell is a `knob` the
+  agent may set within its declared range.
+- `capabilities`: functions the agent may call, each with a policy.
+- `decisions`: the program stops and asks which way to go; every decision
+  has a default and a timeout, so the program never waits forever.
+- `turns`: the program hands the agent a bounded moment to act.
+
+Plus `lifecycle` (pause, resume, stop, restart, status: what a supervising
+harness may do to the process), `attention` (what wakes the agent, and a
+budget on it), and `network`, optional: the agent may meet the agents of
+other programs on an agent network, and its `doc` sentence tells the agent
+how the members it sees relate to this program's own names. abai carries
+only the basic acts here (an identity on a network, who is on it, who is
+reachable, a message sent to a member, a message received as a wake);
+how agents find each other and what they say is each program's own, in
+its declaration and its content.
+
+Three modes. `turns`: one process, one thread, the agent runs only inside
+a touchpoint; the simplest, the natural first rung for a command-line
+program. `thread`: one process, the agent live beside the program once
+it is attached (`await app.attach()` at startup, or any touchpoint), with
+no touchpoint needed after that; in Node the harness runs on the
+program's event loop between its callbacks, which the manifest states as
+a deviation, so a long synchronous step on either side delays the other.
+`sidecar`: the harness is a separate process, attached through a socket;
+the reference mode, the one with the whole lifecycle channel. A manifest
+declares the modes it supports; the first is the default; `ABAI_MODE`
+overrides at startup.
+
+Principles that bind everything you do:
+
+1. The program owns `main()`. The library is included; it wraps nothing
+   and replaces no entry point.
+2. The agent is invited: it acts through declared channels at declared
+   touchpoints and nowhere else.
+3. The program runs without the agent. No harness, a failed harness, a
+   missing model: the program is the plain program. Defaults everywhere.
+4. Declared, not discovered: the agent learns the program from the
+   manifest and its `doc` fields.
+5. Control has policy (`auto`, `confirm`, `forbid`) and leaves an audit
+   trail.
+6. It costs the program nothing it did not ask for: a detached channel
+   operation is a load or two; attached, nothing on the program's thread
+   allocates, locks or blocks except the touchpoints the program itself
+   placed.
+
+How a person meets the agent: `<prog> abai` opens a session on the
+terminal; `<prog> abai run -- ARGS` starts the program under the harness
+with the whole lifecycle channel; `<prog> abai mcp` serves the agent's
+tools to an MCP client such as Claude Code, whose own agent then is the
+program's. All of that comes from a few inserted lines at the top of
+`main()` (section 3).
+
+## 2. Declaring one in TypeScript (declare)
+
+Install (section 5 has the exact command for this machine):
+
+```
+npm install {{abai_spec}} {{harness_spec}}
+```
+
+One module declares the abaigram and exports it. Everything below is
+real API; copy what you need and delete the rest.
+
+```ts
+// src/abai.ts
+import { fileURLToPath } from "node:url";
+import { createAbaigram } from "@abaigram/abai-stub";
+
+export const app = createAbaigram(
+	{
+		name: "myprog",                        // the program's name; also the manifest's
+		entry: "node dist/main.js abai",       // how the entry is reached: a runnable command line
+		modes: ["turns", "thread", "sidecar"], // supported; the first is the default
+		content: { identity: "abai/identity.md" }, // the prompts; identity is required
+		check: { run: "node dist/main.js --demo" }, // a short command that exercises the channels
+		cells: {
+			"queue.depth": { type: "int", access: "read", doc: "Jobs waiting." },
+			"worker.count": {                     // a knob: readwrite with a default and a range
+				type: "int", access: "readwrite", default: 4, range: [1, 64],
+				doc: "Active workers. The pool resizes at the next batch.",
+			},
+		},
+		events: {
+			"job.failed": {
+				payload: { job_id: { type: "string", max: 64 }, attempt: "int" },
+				wakes: "attempt gt 2",            // "always", "never", or <field> eq|ne|gt|lt <json>
+				doc: "A job failed; past two attempts the agent is woken.",
+			},
+		},
+		capabilities: {
+			"job.retry": {
+				params: { job_id: "string" },
+				result: { ok: "bool" },
+				effect: "mutate",                 // "read" or "mutate"
+				policy: "confirm",                // "auto" | "confirm" | "forbid"; mutate defaults to confirm
+				dispatch: "immediate",            // run now. The default is "safepoint": the call waits for
+				                                  // app.safepoint(), so a program that never calls safepoint()
+				                                  // must declare "immediate", or the call stays pending and
+				                                  // check never reaches L3
+				timeout: "30s",
+				example: { job_id: "job-0001" },  // check calls this; make it safe
+				doc: "Requeue a failed job once.",
+				handler: async ({ job_id }) => ({ ok: await retry(String(job_id)) }),
+			},
+		},
+		decisions: {
+			on_backlog: {
+				context: { depth: "int", workers: "int" },
+				options: ["scale_up", "shed_oldest", "wait"],
+				default: "wait",
+				timeout: "5s",
+				doc: "Asked when the backlog crosses the high-water mark.",
+			},
+		},
+		turns: {
+			end_of_batch: { timeout: "30s", doc: "After each batch. The agent may tune worker.count." },
+		},
+		lifecycle: {
+			pause: "cooperative",                 // "cooperative" | "os" | "none"
+			stop: { graceful: "10s", handler: () => shutdown() },
+		},
+		network: {                              // optional: the agent may be a member of an agent network
+			doc: "Members are other job queues of this fleet; a member's name is its host name.",
+			required: false,                      // true: a run with no membership attaches no agent
+		},
+	},
+	// the directory holding abaigram.yaml and abai/: one level up from src/abai.ts and from dist/abai.js;
+	// count the levels from the built file if the build nests deeper (dist/src/abai.js is two)
+	{ root: fileURLToPath(new URL("..", import.meta.url)) },
+);
+```
+
+Using it from the program's own code, wherever the facts already are.
+Obtain the handles once, at startup; `set`, `get` and `emit` are the cheap
+calls. The import is in the repository's own style: `./abai.js` under
+NodeNext (tsc resolves it to `abai.ts`), `./abai.ts` only where the project
+runs or rewrites `.ts` imports.
+
+```ts
+import { app } from "./abai.js";
+
+const depth = app.cell<number>("queue.depth");
+const workers = app.knob<number>("worker.count");
+const failed = app.event("job.failed");
+
+depth.set(queue.length);                               // one store, always cheap
+const n = workers.get();                               // the agent's setting, or the default
+failed.emit({ job_id, attempt });                      // nothing happens when no harness is attached
+const choice = await app.decide<string>("on_backlog", { depth: queue.length, workers: n }); // "wait" when nobody answers
+await app.turn("end_of_batch");                        // returns at once when nobody is there
+app.safepoint();                                       // where "safepoint" calls and a pause take effect
+await app.attach();                                    // ask for the agent now: optional in turns mode, a thread program's first act
+```
+
+abai is ESM-only. In a CommonJS repository load it inside the async main:
+`const { createAbaigram, runEntry } = await import("@abaigram/abai-stub");` (Node 22.12 and
+later can also `require("@abaigram/abai-stub")`). Under `verbatimModuleSyntax` the imports
+above are all value imports and need no change; a type you import, such as
+`Abaigram`, needs `import type`.
+
+Types: `int`, `float`, `bool`, `enum` (with `enum: [...]`), `string`,
+`object` (with `fields`), `list` (with `items`); sized types carry `max`.
+A schema field is a bare type name or `{ type, max, enum, fields, items,
+nullable, doc }`. A knob is `access: "readwrite"` with a `default`; a
+scalar knob lands in shared state, a sized one is delivered to
+`app.knob(name).onChange(handler)` at a safepoint. Capabilities may also
+be bound late: `app.capability("job.retry", handler)`.
+
+Policy (section 10 of the contract): `auto` runs on the agent's say,
+`confirm` asks the person first (under an MCP client, the client's own
+permission prompt is the person's consent), `forbid` is declared but never
+runnable. Every act is written to the audit log with the agent's reason.
+
+Cost: detached, every operation above is a load or a store. Keep your own
+handlers cheap too; the agent's model calls never run on the program's
+thread in sidecar mode, in turns mode they run only inside the
+touchpoints you placed, and in thread mode the agent's own work runs on
+the program's event loop between its callbacks, so a slow synchronous
+step on either side delays the other.
+
+## 3. The standard entry (entry)
+
+Every abaigram answers `<prog> abai ...`. The stub provides it; the
+program hands it the arguments first thing in `main()`:
+
+```ts
+import { runEntry } from "@abaigram/abai-stub";
+import { app } from "./abai.js";
+
+async function main(): Promise<void> {
+	const code = await runEntry(app, process.argv.slice(2));
+	if (code >= 0) {
+		process.exitCode = code; // an abai verb ran and said what it had to say
+		return;
+	}
+	// -1: no abai verb; the program's own argument handling follows, untouched
+}
+```
+
+In a module that already runs at top level, the same two statements stand
+on their own: `const code = await runEntry(app, process.argv.slice(2)); if
+(code >= 0) process.exit(code);`. Prefer `process.exitCode` where you can:
+`process.exit` can cut a large `manifest --json` short on a pipe, and
+`abaikit check` reads the entry through one.
+
+Added lines, nothing removed: the program's own argument parsing follows
+untouched, and a plain invocation reaches it exactly as before.
+
+The verbs the entry serves:
+
+```
+<prog> abai                  open a session (needs a configured model)
+<prog> abai install          run the install touchpoint
+<prog> abai run -- ARGS      sidecar launch: the harness starts "<prog> ARGS" as its child
+<prog> abai config           machine-level model and credential settings (~/.abai)
+<prog> abai doctor           offline: manifest, entry, content, modes; online: the model
+<prog> abai manifest         print the effective manifest
+<prog> abai mcp              serve the agent's tools to an MCP client over stdio
+```
+
+The manifest exists twice and must agree: in code (the source of truth at
+runtime) and as `abaigram.yaml` at the repository root, generated by the
+program itself and checked in:
+
+```
+<entry> manifest > abaigram.yaml
+<entry> doctor --offline
+```
+
+The `entry` field is a command line that runs in the repository root; the
+tools reach the program through it. `node dist/main.js abai`, `npx myprog
+abai`, `./bin/myprog abai` are all fine; `myprog abai` only once `myprog`
+is on the PATH.
+
+Content lives in `abai/` at the root unless the manifest says otherwise:
+`abai/identity.md` (required: who the agent is for this program and how
+it should behave), `abai/install.md`, `abai/use.md`, `abai/turns/<name>.md`.
+The harness composes the system prompt from `identity`, the mode, and
+every declaration rendered with its `doc`. Good `doc` fields are most of
+the work of good content.
+
+## 4. Conformance levels and what check demands (levels)
+
+No level needs a model. `abaikit check <repo>` verifies them with the
+null harness, a harness that attaches and drives nothing (passive) or
+drives every declared knob and capability by its declared default and
+`example` (active, the "exercise run").
+
+| Level | Name | Requires |
+|---|---|---|
+| L1 | reachable | The stub is included; `<entry> manifest` works; `abaigram.yaml` exists, validates and agrees with the code; `abai/identity.md` exists; the offline `doctor` passes. Checked without running the program beyond its entry. |
+| L2 | observable | L1, plus `check.run`, plus at least one cell written or event emitted during the exercise run. |
+| L3 | steerable | L2, plus one capability the exercise calls successfully with its `example`, or one knob whose write lands. |
+| L4 | deliberative | L3, plus one decision the program reaches during the exercise run. |
+
+L1 is what `<entry> doctor --offline` checks; `abaikit check` repeats it
+from outside and adds the levels above.
+
+`check.run` is a command, run by the shell in the repository root, that
+exercises the program's channels and exits: a demo mode, a short batch, a
+dry run. `check` runs it with `ABAI_HARNESS=exercise` (the active null
+harness, which also stands in for the person's consent on `confirm`
+acts) under each declared mode (`ABAI_MODE`), and reads the report the
+stub prints at exit. It then measures: the same command with
+`ABAI_HARNESS=off` (nothing attaches) and `ABAI_HARNESS=null` (the
+passive harness), side by side; a declared `check.overhead` (such as
+`"5%"`) fails the check when the null run is slower than that. Every
+declaration the exercise could not reach is named in the report,
+capabilities without an `example` included. The exercise and measurement
+runs attach the null harness, so the audit log the manifest names
+receives their records: keep that file out of version control, or point
+`audit.path` outside the checkout.
+
+```
+abaikit check <repo>              # the level reached, modes, overhead, unexercised, violations
+abaikit check <repo> --level 3    # exit non-zero below level 3
+abaikit check <repo> --json
+```
+
+A program is at the level `check` can demonstrate, not the level you
+intended. If a channel is only reached by a path `check.run` does not
+take, change `check.run`, not the claim.
+
+## 5. The retrofit, step by step (retrofit)
+
+Follow the repository's own guidelines and conventions first: its
+`AGENTS.md` or `CONTRIBUTING.md`, its module system (ESM or CommonJS,
+TypeScript or JavaScript), its linter and formatter, its test command.
+Everything you add is additive: new files, inserted lines, two added
+dependencies. You never rewrite `main()`, never delete a line, never
+reorder existing code.
+
+Step 0. Know the program. Find the package manifest, the entry file the
+`bin` or `main` points at, how it is built and run, and where its state
+already lives (a queue, a counter, a config). Verify: you can name the
+file where the program's own argument handling starts, and the command
+that runs the program.
+
+Step 1. Add the dependencies, in the repository root.
+
+```
+npm install {{abai_spec}} {{harness_spec}}
+```
+{{workspace_note}}
+Verify, in the repository root:
+`node -e "import('@abaigram/abai-stub').then(m => console.log(m.ABAI_STUB_VERSION))"`
+prints `{{stub}}`.
+
+Step 2. Declare the abaigram in a new module (`src/abai.ts`, or
+`src/abai.js` in a JavaScript repository) as in section 2, with only
+`name`, a runnable `entry`, `modes: ["turns", "sidecar"]` (add `"thread"`
+when the program keeps running between touchpoints and wants the agent
+live in its process; it then calls `await app.attach()` at startup),
+`content` and `root` to begin with. When the program's real entry is a
+plain launcher that runs without the build (a `bin/x.mjs` that imports
+`dist/`), put the declaration beside it as a `.mjs` module the launcher
+can import, so the entry answers `manifest` and `doctor` before anything
+is built. Verify: build as the repository does, then
+`node -e "import('./dist/abai.js')"` (the built path) runs without error.
+
+Step 3. Hook the entry. In the file where `main()` starts, insert the
+lines of section 3 before the program's own argument handling. The entry
+runs the built program, so from here on every change is: build (the
+repository's build script), then `<entry> manifest > abaigram.yaml`, then
+verify. Verify: `<entry> manifest` prints YAML, and the program's own
+usage (`<prog> --help`, or whatever it answered before) is unchanged.
+
+Step 4. Write `abai/identity.md`: who the agent is for this program, what
+it is for, how it should behave, in a few sentences. Verify:
+`<entry> doctor --offline` prints an `identity` line that begins with `ok`.
+
+Step 5. Generate the manifest file and reach L1.
+
+```
+<entry> manifest > abaigram.yaml
+abaikit check .
+```
+
+Verify: the report says level 1. Commit `abaigram.yaml`, `abai/`, the new
+module, the inserted lines, `package.json` and its lock file; nothing else
+changed.
+
+Step 6. Observe: L2. Declare one or two cells and events where the program
+already has the facts (a depth, a count, a failure), and set or emit them
+in the existing code paths, one line each. Add `check: { run: "<a short
+command that exercises them>" }` to the declaration, a mode of the
+program that runs for seconds and exits (a `--demo` flag you add, a small
+fixed input, a dry run). Build, regenerate `abaigram.yaml`, verify: `abaikit check .
+--level 2`.
+
+Step 7. Steer: L3. Declare one knob the program already reads as a
+setting (with its current value as the `default` and a safe `range`), or
+one capability with a handler and an `example` whose call is harmless.
+Build, regenerate, verify: `abaikit check . --level 3`; the report names
+the knob as landed or the capability as called.
+
+Step 8. Deliberate: L4. At a real fork in the program (retry or give up,
+scale or wait), declare a decision with `options`, a `default` that is
+what the program does today, and a short `timeout`; insert `const choice
+= await app.decide("on_retry", { ... })` above the fork and add a branch
+on `choice`, the existing path staying as the branch the default chooses.
+Make sure `check.run` reaches the fork. Build, regenerate, verify:
+`abaikit check . --level 4`.
+
+Step 9. Meet the agent. With a model configured (`<entry> config set
+provider ...`, `<entry> config set model ...`, `<entry> config set key
+...`, then `<entry> doctor`), open `<entry>` and ask what it sees; or run
+`<entry> run -- ARGS` and watch it supervise; or serve `<entry> mcp` to
+Claude Code (section 6). Say what you added and why in the commit
+message and, if the repository keeps one, its changelog.
+
+If `abaikit check` reports a violation, read its location and message:
+they name the file or the declaration and what the contract wanted.
+
+## 6. Running an abaigram (use)
+
+Session on the terminal, the person talking to the agent while the
+program runs (turns and thread modes in-process; sidecar attaches to or
+starts the harness binary):
+
+```
+<entry>
+```
+
+Launch under supervision, the harness as the parent with the whole
+lifecycle channel (pause, resume, stop, restart, status) and the
+program's output observed from outside:
+
+```
+<entry> run -- ARGS
+abaikit run <repo> -- ARGS        # the same, from outside the repository
+```
+
+An MCP client as the agent, no model configured anywhere: the client's
+own agent uses the program's tools, and the client's permission prompt is
+the person's consent.
+
+```json
+{ "mcpServers": { "myprog": { "command": "node", "args": ["/abs/path/to/dist/main.js", "abai", "mcp"] } } }
+```
+
+(An absolute path, or run `claude` from the repository root: the client
+starts the command from wherever it is.)
+
+```
+claude -p "what is the program doing?" --mcp-config mcp.json --strict-mcp-config --allowedTools "mcp__myprog__*"
+```
+
+The machine-level model configuration, shared by every abaigram on the
+machine, lives under `~/.abai/`:
+
+```
+<entry> config providers                   # every provider and the login it offers
+<entry> config set provider <id>
+<entry> config set model <id>
+<entry> config login <provider>            # sign in with an account; --api-key for a key, --browser opens the URL
+<entry> config set key <provider>          # a key, read without echo
+<entry> config set url <provider> <base url>
+<entry> doctor                             # offline checks, then the model
+```
+
+Environment variables, all optional: `ABAI_MODE` (`turns`, `thread` or
+`sidecar`, overriding the manifest's first mode), `ABAI_HARNESS` (`off`,
+`null`, `exercise`: check runs only; never set it for real use),
+`ABAI_HOME` (the configuration directory, default `~/.abai`),
+`ABAI_RUN_DIR` (descriptors of running programs, default `~/.abai/run`),
+`ABAI_HARNESS_BIN` (the sidecar harness binary to spawn),
+`ABAI_HARNESS_MODULE` (the in-process harness module to import),
+`ABAI_CHANNEL` (`terminal` or `none`), `ABAI_ATTACH_WAIT_MS` (how long a
+touchpoint waits for a harness), and for the network below `ABAI_NET_DIR`,
+`ABAI_NET_TOKEN` and `ABAI_AIIP_BIN`.
+
+A program that declares `network` puts its agent on an aiip network
+(`~/projects/aiip`: an overlay network for agents, one Go binary, no
+root). The harness talks to aiip's daemon over its socket; the `aiip`
+binary must be on the machine (on the PATH, or named by `ABAI_AIIP_BIN`
+or `<entry> config set aiip-bin <path>`), and `doctor` says when it is
+not. A run's identity lives in a state directory: `ABAI_NET_DIR`, else
+`~/.abai/net/<name>/`, so two runs of one program on one machine are one
+member unless the run is given a directory of its own. At attach the
+harness finds or starts the daemon for that directory, joins with the
+invite in `ABAI_NET_TOKEN` when the run is not yet a member, and tells
+the agent where it is; `abai_peers` lists who else is there and who is
+reachable now. A message from a member wakes the agent as the event
+`abai.net.message`, with the sender's issued name and what it said;
+`abai_send` answers a member by name, with a reason, and `abai_messages`
+lists the run's messages. Every message sent or received is one line in
+the audit log (`act: message`), written by the stub. The envelope on the
+wire is aiap's (`~/projects/agents-cowork`), so an abaigram and an aiap
+agent on one network read each other. A declared network the run cannot
+have is said in the prompt, unless `required` is true, in which case no
+agent attaches.
+
+```
+<entry> config net                                 # the state dir, the daemon, the memberships
+<entry> config net create <network> --as <member>  # a new network, this run as its authority
+<entry> config net invite <network> --for <member> # an invite token for a new member (authority only)
+<entry> config net join --token -                  # join with an invite read from stdin
+<entry> config net leave <network>
+```
+
+An invite token carries the member's private key: hand it to that
+member's run as `ABAI_NET_TOKEN` or on stdin, never in a command line, a
+file or a log, and never over a link that is not encrypted end to end to
+that run. A network has 253 slots besides its authority and no removal:
+every name ever invited takes one, whether or not its holder enrolls, and
+a name whose holder has enrolled is that member's for good. Keep a
+member's state directory, since a lost one cannot rejoin under its name,
+and let the member run now and then: a certificate lasts 30 days and the
+daemon renews it only while it runs, so a member that has not run for 30
+days is locked out just the same. An invite for a name whose holder never
+enrolled reissues that slot with fresh credentials and voids the earlier
+token, so mint a second invite for a name only when the authority's
+roster (`abai_peers`, or the harness client's `members`) shows its holder
+not enrolled and nobody is about to enroll with the first. Who creates
+the network, who mints the invites, how members find each other and what
+they say to one another is the program's to decide, in its code and its
+content, not abai's.
+
+The audit log (`audit.path` in the manifest; default
+`~/.abai/audit/<name>.jsonl`) records every act of control with its
+reason, consent and outcome. Read it when you wonder what the agent did.
+
+## 7. Where this instantiation departs from the contract (deviations)
+
+The first four are in every manifest this stub writes, the fifth when
+`thread` is declared and the last when `sidecar` is, so an agent reading
+the manifest sees them too:
+
+{{deviations}}
+
+## 8. What never to do (never)
+
+- Never rewrite, wrap or replace `main()`. The entry hook is a few
+  inserted lines at its top; the program's own flow follows them.
+- Never delete or reorder existing lines. A retrofit is additive; a
+  reviewer should see only added lines and new files.
+- Never put the stub behind a condition. The entry must be reachable on
+  every invocation, or `check` cannot reach L1.
+- Never leave a capability on the default `safepoint` dispatch in a
+  program that never calls `app.safepoint()`: the call stays pending and
+  `check` never reaches L3.
+- Never block in a handler or a `set`. Long work belongs behind an
+  `immediate`-dispatched async capability, or in a job the handler
+  enqueues.
+- Never declare an `example` whose call changes real state. The exercise
+  run calls it; so will a curious agent.
+- Never declare a knob without a safe `default` and `range`, a decision
+  without the `default` the program chooses today, or a turn without a
+  `timeout`.
+- Never put secrets or credentials in content or `doc` fields; they are
+  the prompt.
+- Never claim a level `check` did not report, and never change a level by
+  editing `abaigram.yaml` by hand: it is generated, and `check` compares
+  it with the code.
+- Never make `check.run` depend on the network, credentials, or state it
+  does not create itself.
+- Never touch `node_modules`, build output, or files `.gitignore` names.

package/abai/use.md

@@ -0,0 +1 @@
+A session with abaikit is about one repository at a time. Start by listing it and reading its package manifest and entry file; propose before you write; after every write, run check and read its report.