janissary 0.5.1 → 0.5.4

package/ai/guidelines/architecture-principles.md

@@ -0,0 +1,75 @@
+# architecture principles
+
+Guidance for developers and AI assistants evolving this codebase. These principles are derived from the current architecture (a Node server in `src/` driving a React SPA in `web/` over one WebSocket) and from established practice for authoritative client-server, actor-style, and type-safe full-stack systems.
+
+When a change conflicts with a principle, that is a design discussion — not a thing to silently work around. Prefer the smallest change that keeps every principle true.
+
+---
+
+## 1. The server is the single source of truth; the client is a thin projection
+
+The server owns all state and all rendering decisions. It runs `flattenBuffer` and ships `BufferLine[]` per tab, so the client never re-implements transcript logic — it renders snapshots and emits *intents* (`{ method, params }`), never derived state. This is the authoritative client-server model: the server validates every request and broadcasts a definitive snapshot rather than clients broadcasting isolated events.
+
+**Rule.** Presentation logic that affects *what* is shown lives on the server. The client may own only ephemeral, view-local concerns (scroll position, which modal is open, cursor). Never fork a piece of state so both sides compute it — if the client needs it, the server sends it.
+
+## 2. Each agent is one session object that owns its state
+
+Today per-tab state is scattered across a dozen parallel maps in `Controller` — `shells`, `cwd`, `busy`, `harnessOf`, `acpSessions`, `acpInfo`, `ptys`, `schedules`, `tabDbConns`, `context`, `browsers`, `workspaces` — all keyed by label. Every new per-tab concern adds another map, and every lifecycle path must remember to touch all of them. The actor model is the antidote: encapsulate one agent's state behind one owner, mutated only through well-defined methods.
+
+**Rule.** New per-agent state belongs *on the agent's session object*, not in a new `Map<label, …>` on the controller. An agent owns its shell, PTYs, ACP session, browser, schedule, and connections; nothing reaches into those from outside except through its methods.
+
+## 3. The controller dispatches; feature services execute
+
+`controller.ts` is ~1130 lines and violates the project's own 200-line guideline by 5×. It is a classic God Object: command routing, shell I/O, PTY management, ACP loops, browser glue, scheduling, messaging, globbing, file serving, and persistence all in one class. Controller methods should be light — routing and orchestration — with the real work in focused, independently testable modules. (Self-contained command logic has moved out into `src/commands/*.ts` per principle 5; the remaining bulk is the per-tab resource machinery principle 2 targets.)
+
+**Rule.** The controller maps an intent to a feature and delegates. Business logic lives in feature modules (`shell`, `db`, `browser-tab`, `schedule`, `messaging`, `acp-loop`, openers). When you find yourself adding a method to the controller, ask whether it belongs to a feature instead. Keep files at or under **200 lines**; a file that exceeds it is signalling that it should be split.
+
+## 4. Parse pure, execute effectful — and never blur the seam
+
+The codebase's biggest strength: `parseXCommand` functions (`parseDbCommand`, `parseScheduleCommand`, `parseConnectionCommand`, `parseOpen`, the recognizers) are pure — they return structured data or `{ error }` and do no I/O. Side effects live in the execution layer. This makes parsing trivially testable and routing predictable.
+
+**Rule.** A parser returns a value; it never spawns a process, touches the filesystem, mutates state, or writes to a transcript. Effects happen only in the execution layer, which consumes parsed data. Protect this seam — it is why the recognizers and command tests stay simple.
+
+## 5. One command, one definition — delete shadow systems
+
+Each command has exactly **one** definition. Self-contained commands (`state`, `next`, `quit`, `hist`, `clear`, `msg`, `broadcast`, `schedule`, `db`) own their logic in `src/commands/<name>.ts` through a `run(command, CommandContext)` method; the controller builds the `CommandContext` for the tab and delegates. Commands that need the tab/PTY/session machinery the controller owns (`agent`, `profile`, `close`, `connection`, `acp`, `open`, `browser`) carry only `name`/`match` and execute in the controller's `runApp`. The earlier shadow system — vestigial `handler` functions plus the 40-field `CommandHandlerContext` describing a React-hook world that no longer existed — has been deleted; `CommandContext` is the single, narrow controller-facing surface.
+
+**Rule.** Each command has exactly one definition and one execution path. When a migration leaves scaffolding behind, removing it is part of finishing the migration — not a separate "cleanup" someday. No code path that the system never takes. A new self-contained command belongs in its module behind `CommandContext`; only reach into the controller when a command genuinely needs machinery the context does not expose.
+
+## 6. Every acquire has a matching release (symmetric lifecycle)
+
+A tab can own a shell, PTYs, an ACP session and its info, a browser, a workspace clone, served `open` files, schedules, db-connection attributions, and message context. `closeTab` and `shutdown` must today manually tear down each one, in two places, from memory — a leak is one forgotten line away. Actors solve this by giving each entity a single `dispose()`; acquisition and release live together.
+
+**Rule.** Resource acquisition and teardown are defined together, by the owner. Closing an agent disposes everything it owns through one call, not a hand-maintained checklist. If you add a resource to an agent, you add its teardown in the same change.
+
+## 7. One wire contract, shared — not mirrored
+
+`src/protocol.ts` and `web/src/protocol.ts` are kept in sync by hand ("the web bundle mirrors these locally… keep them in sync"). Manually mirrored types are the textbook cause of type drift: change an event shape on one side, forget the other, and the bug surfaces only at runtime. A single shared definition makes the compiler flag every affected site across both apps.
+
+**Rule.** Wire types (`ServerEvent`, `ClientMessage`, `TabView`, …) have exactly one definition that both server and client import. Treat manual mirroring as technical debt to retire, and until then, any change to one file must be made to the other in the same commit.
+
+## 8. Synchronize by minimal, ordered change — not whole-world snapshots
+
+`emitState` broadcasts the *entire* `view()` — every tab and every buffer line — on essentially every mutation (keystroke-driven shell output, each ACP chunk, each tick). It is simple and correct today at local-only scale, but it does not bound payload size or survive reconnection gracefully ("what did the client miss?" is the hardest WebSocket problem). The maturity path is sequence numbers or event sourcing so a reconnecting client replays only the delta.
+
+**Rule.** Prefer sending what changed over re-sending the world. When adding high-frequency or large state, consider per-tab/targeted updates and a sequence/version so the client can detect gaps and resync. Keep the door open to reconnection-aware sync; don't bake in "full snapshot every event" as a load-bearing assumption.
+
+## 9. Local-first security is an enforced, tested invariant
+
+The strongest boundary in the system: the server binds to `127.0.0.1`, requires a per-session token on the WS upgrade, enforces a loopback Host/Origin allowlist (the DNS-rebinding guard), and serves local files *only* from the controller's `/open/<id>` allow-list — an arbitrary path is never reachable. This is verified by tests (bad token rejected, spoofed Host → 403).
+
+**Rule.** Every new ingress — an HTTP route, an RPC method, a served file, a spawned process — passes through the same token + Origin/Host guard and, for files, an explicit allow-list. Never widen reach (bind beyond loopback, accept an unauthenticated route) without re-deriving the threat model first, and ship a test that pins the boundary.
+
+## 10. Specs and docs are source of truth — and they evolve with the code
+
+`product/specs/` is declared authoritative ("when behavior is ambiguous, the spec is the source of truth"), yet architecture docs here have gone stale before: earlier docs (`AI.md`, a migration map) described components like `cli.tsx` and `src/server/*` paths long after they were removed or flattened into `src/`. Documentation that lies about the code is worse than none — it actively misleads both humans and AI agents.
+
+**Rule.** A behavior change updates its `product/specs/` file in the same change; a structural change updates the architecture docs (`CLAUDE.md`'s project-structure section, the affected `ai/guidelines/` files) in the same change. Behavior ships with a test (vitest, colocated `*.test.ts(x)`) — the suite is the executable half of the spec. Stale architecture docs are bugs; fix them on sight.
+
+---
+
+## How to use these
+
+- **Developers:** before opening a PR, check it against principles 2–7 (the ones most easily eroded). If you added a `Map<label, …>` to the controller, grew a file past 200 lines, or edited one `protocol.ts` but not the other, reconsider.
+- **AI assistants:** treat these as constraints, not suggestions. When asked to "add a feature," default to a feature module + a session-owned resource, wire one command definition, update the spec and a test, and keep the controller change to delegation. Surface — don't silently resolve — any request that forces a principle to break.
+</content>

package/ai/guidelines/code-guidelines.md

@@ -0,0 +1,17 @@
+# Code Guidelines
+
+## File Size
+
+- JavaScript/TypeScript files should be limited to **200 lines of code**.
+- When a file exceeds this limit, the **only** acceptable way to shrink it is to
+  **extract some of its code into another file** (a new, focused module) and import it
+  back. Move a cohesive group of related logic out, don't shave lines off in place.
+- Do **not** try to get under the limit by compacting code, removing comments, or
+  deleting blank lines/spacing. These hurt readability without improving the design and
+  are not a valid response to the line limit.
+
+## Modularization
+
+- Code that belongs to a single feature or functional area should be grouped in its own file.
+- A file should have one clear responsibility. Avoid mixing unrelated concerns in the same file.
+- Prefer small, focused modules over large, monolithic files.

package/ai/guidelines/conventional-commits.md

@@ -0,0 +1,192 @@
+
+# Conventional Commits 1.0.0
+
+## Summary
+
+The Conventional Commits specification is a lightweight convention on top of commit messages.
+It provides an easy set of rules for creating an explicit commit history;
+which makes it easier to write automated tools on top of.
+This convention dovetails with [SemVer](http://semver.org),
+by describing the features, fixes, and breaking changes made in commit messages.
+
+The commit message should be structured as follows:
+
+---
+
+```
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+---
+
+<br />
+The commit contains the following structural elements, to communicate intent to the
+consumers of your library:
+
+1. **fix:** a commit of the _type_ `fix` patches a bug in your codebase (this correlates with [`PATCH`](http://semver.org/#summary) in Semantic Versioning).
+1. **feat:** a commit of the _type_ `feat` introduces a new feature to the codebase (this correlates with [`MINOR`](http://semver.org/#summary) in Semantic Versioning).
+1. **BREAKING CHANGE:** a commit that has a footer `BREAKING CHANGE:`, or appends a `!` after the type/scope, introduces a breaking API change (correlating with [`MAJOR`](http://semver.org/#summary) in Semantic Versioning).
+A BREAKING CHANGE can be part of commits of any _type_.
+1. _types_ other than `fix:` and `feat:` are allowed, for example [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (based on the [Angular convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) recommends `build:`, `chore:`,
+  `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, and others.
+1. _footers_ other than `BREAKING CHANGE: <description>` may be provided and follow a convention similar to
+  [git trailer format](https://git-scm.com/docs/git-interpret-trailers).
+
+Additional types are not mandated by the Conventional Commits specification, and have no implicit effect in Semantic Versioning (unless they include a BREAKING CHANGE).
+<br /><br />
+A scope may be provided to a commit's type, to provide additional contextual information and is contained within parenthesis, e.g., `feat(parser): add ability to parse arrays`.
+
+## Examples
+
+### Commit message with description and breaking change footer
+```
+feat: allow provided config object to extend other configs
+
+BREAKING CHANGE: `extends` key in config file is now used for extending other config files
+```
+
+### Commit message with `!` to draw attention to breaking change
+```
+feat!: send an email to the customer when a product is shipped
+```
+
+### Commit message with scope and `!` to draw attention to breaking change
+```
+feat(api)!: send an email to the customer when a product is shipped
+```
+
+### Commit message with both `!` and BREAKING CHANGE footer
+```
+feat!: drop support for Node 6
+
+BREAKING CHANGE: use JavaScript features not available in Node 6.
+```
+
+### Commit message with no body
+```
+docs: correct spelling of CHANGELOG
+```
+
+### Commit message with scope
+```
+feat(lang): add Polish language
+```
+
+### Commit message with multi-paragraph body and multiple footers
+```
+fix: prevent racing of requests
+
+Introduce a request id and a reference to latest request. Dismiss
+incoming responses other than from latest request.
+
+Remove timeouts which were used to mitigate the racing issue but are
+obsolete now.
+
+Reviewed-by: Z
+Refs: #123
+```
+
+## Specification
+
+The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).
+
+1. Commits MUST be prefixed with a type, which consists of a noun, `feat`, `fix`, etc., followed
+  by the OPTIONAL scope, OPTIONAL `!`, and REQUIRED terminal colon and space.
+1. The type `feat` MUST be used when a commit adds a new feature to your application or library.
+1. The type `fix` MUST be used when a commit represents a bug fix for your application.
+1. A scope MAY be provided after a type. A scope MUST consist of a noun describing a
+  section of the codebase surrounded by parenthesis, e.g., `fix(parser):`
+1. A description MUST immediately follow the colon and space after the type/scope prefix.
+The description is a short summary of the code changes, e.g., _fix: array parsing issue when multiple spaces were contained in string_.
+1. A longer commit body MAY be provided after the short description, providing additional contextual information about the code changes. The body MUST begin one blank line after the description.
+1. A commit body is free-form and MAY consist of any number of newline separated paragraphs.
+1. One or more footers MAY be provided one blank line after the body. Each footer MUST consist of
+ a word token, followed by either a `:<space>` or `<space>#` separator, followed by a string value (this is inspired by the
+  [git trailer convention](https://git-scm.com/docs/git-interpret-trailers)).
+1. A footer's token MUST use `-` in place of whitespace characters, e.g., `Acked-by` (this helps differentiate
+  the footer section from a multi-paragraph body). An exception is made for `BREAKING CHANGE`, which MAY also be used as a token.
+1. A footer's value MAY contain spaces and newlines, and parsing MUST terminate when the next valid footer
+  token/separator pair is observed.
+1. Breaking changes MUST be indicated in the type/scope prefix of a commit, or as an entry in the
+  footer.
+1. If included as a footer, a breaking change MUST consist of the uppercase text BREAKING CHANGE, followed by a colon, space, and description, e.g.,
+_BREAKING CHANGE: environment variables now take precedence over config files_.
+1. If included in the type/scope prefix, breaking changes MUST be indicated by a
+  `!` immediately before the `:`. If `!` is used, `BREAKING CHANGE:` MAY be omitted from the footer section,
+  and the commit description SHALL be used to describe the breaking change.
+1. Types other than `feat` and `fix` MAY be used in your commit messages, e.g., _docs: update ref docs._
+1. The units of information that make up Conventional Commits MUST NOT be treated as case-sensitive by implementors, with the exception of BREAKING CHANGE which MUST be uppercase.
+1. BREAKING-CHANGE MUST be synonymous with BREAKING CHANGE, when used as a token in a footer.
+
+## Why Use Conventional Commits
+
+* Automatically generating CHANGELOGs.
+* Automatically determining a semantic version bump (based on the types of commits landed).
+* Communicating the nature of changes to teammates, the public, and other stakeholders.
+* Triggering build and publish processes.
+* Making it easier for people to contribute to your projects, by allowing them to explore
+  a more structured commit history.
+
+## FAQ
+
+### How should I deal with commit messages in the initial development phase?
+
+We recommend that you proceed as if you've already released the product. Typically *somebody*, even if it's your fellow software developers, is using your software. They'll want to know what's fixed, what breaks etc.
+
+### Are the types in the commit title uppercase or lowercase?
+
+Any casing may be used, but it's best to be consistent.
+
+### What do I do if the commit conforms to more than one of the commit types?
+
+Go back and make multiple commits whenever possible. Part of the benefit of Conventional Commits is its ability to drive us to make more organized commits and PRs.
+
+### Doesn’t this discourage rapid development and fast iteration?
+
+It discourages moving fast in a disorganized way. It helps you be able to move fast long term across multiple projects with varied contributors.
+
+### Might Conventional Commits lead developers to limit the type of commits they make because they'll be thinking in the types provided?
+
+Conventional Commits encourages us to make more of certain types of commits such as fixes. Other than that, the flexibility of Conventional Commits allows your team to come up with their own types and change those types over time.
+
+### How does this relate to SemVer?
+
+`fix` type commits should be translated to `PATCH` releases. `feat` type commits should be translated to `MINOR` releases. Commits with `BREAKING CHANGE` in the commits, regardless of type, should be translated to `MAJOR` releases.
+
+### How should I version my extensions to the Conventional Commits Specification, e.g. `@jameswomack/conventional-commit-spec`?
+
+We recommend using SemVer to release your own extensions to this specification (and
+encourage you to make these extensions!)
+
+### What do I do if I accidentally use the wrong commit type?
+
+#### When you used a type that's of the spec but not the correct type, e.g. `fix` instead of `feat`
+
+Prior to merging or releasing the mistake, we recommend using `git rebase -i` to edit the commit history. After release, the cleanup will be different according to what tools and processes you use.
+
+#### When you used a type *not* of the spec, e.g. `feet` instead of `feat`
+
+In a worst case scenario, it's not the end of the world if a commit lands that does not meet the Conventional Commits specification. It simply means that commit will be missed by tools that are based on the spec.
+
+### Do all my contributors need to use the Conventional Commits specification?
+
+No! If you use a squash based workflow on Git lead maintainers can clean up the commit messages as they're merged—adding no workload to casual committers.
+A common workflow for this is to have your git system automatically squash commits from a pull request and present a form for the lead maintainer to enter the proper git commit message for the merge.
+
+### How does Conventional Commits handle revert commits?
+
+Reverting code can be complicated: are you reverting multiple commits? if you revert a feature, should the next release instead be a patch?
+
+Conventional Commits does not make an explicit effort to define revert behavior. Instead we leave it to tooling
+authors to use the flexibility of _types_ and _footers_ to develop their logic for handling reverts.
+
+One recommendation is to use the `revert` type, and a footer that references the commit SHAs that are being reverted:
+
+```
+revert: let us never again speak of the noodle incident
+
+Refs: 676104e, a215868
+```

package/ai/guidelines/developer-documentation.md

@@ -0,0 +1,124 @@
+# Writing Developer Documentation
+
+Guidance for docs aimed at contributors, not end users: `product/specs/`, `product/plans/`, `ai/guidelines/`
+itself, and the developer-facing parts of `README.md`. The audience already knows how to run the
+app and wants to know how it's built and why — the opposite orientation from
+[[user-documentation]], which assumes no codebase knowledge at all. For sentence-level tone, see
+[[human-writing-guidelines]].
+
+## Specs describe behavior precisely, not just architecture
+
+Every file in `product/specs/` is a **behavior spec**, not a design essay: it should let a contributor
+predict exactly what the app does for a given input, including edge cases and error messages,
+without reading the implementation. The existing specs in this repo already establish the house
+style — match it rather than inventing a new one:
+
+- **Cross-reference with `[[name]]`** where `name` matches another spec's filename (minus `.md`),
+  so related behavior links up without duplicating explanation. A `[[link]]` to a spec that doesn't
+  exist yet is fine — it marks something worth writing, not an error.
+- **Name the implementation** where it disambiguates behavior: the function, file, or module that
+  owns a piece of logic (`ScheduleManager` in `src/schedule-manager.ts`, `flattenBuffer` in
+  `src/tab.ts`). This is the opposite rule from user documentation, which must never do this — a
+  spec's reader is the person who will go read that file next.
+- **State the exact error and usage messages**, verbatim, not paraphrased — a contributor
+  implementing a caller needs the literal string, and a paraphrase invites drift between the spec
+  and the code.
+- **Cover edge cases as a first-class section**, not a footnote: what happens on a duplicate name,
+  an empty result, a missing target, a malformed invocation. These are exactly the cases a reader
+  can't infer from the happy path alone.
+- **Explain the "why" inline, briefly, at the point of the surprising decision** — not as a
+  separate essay. A one-sentence rationale next to the rule it justifies (why secrets are denied
+  last in the sandbox profile, why `TMPDIR` is overridden) is worth more than a wall of prose
+  elsewhere that the reader has to go find.
+
+## README: minimize time-to-first-success
+
+The README is the first developer-facing doc a contributor reads, and its job is narrower than
+it looks: get someone from "I found this repo" to "I ran it / made my first change" as fast as
+possible — not to hold the whole architecture.
+
+- The first couple of lines should answer what the project is and why someone would want it;
+  everything else is secondary to that.
+- Lead with the smallest working example — the actual install/run commands, verbatim — before
+  architecture or design discussion. A contributor's first goal is a working local setup, the same
+  "time-to-first-call" instinct API docs optimize for.
+- Push deep detail (architecture rationale, full command reference) out to `product/specs/` and link to it,
+  rather than growing the README past what a newcomer needs on day one. A README bloated with
+  reference material makes the one thing it must do — get someone running — harder to find.
+- Keep it current the same way as any other doc here: a setup-affecting change updates the README
+  in the same PR.
+
+## Onboarding: answer "where do I look first?"
+
+A new contributor's first real question is where things live and how to find them — not what
+every subsystem does. The onboarding-relevant docs in this repo (`README.md`, `CLAUDE.md`,
+`ai/guidelines/`) should collectively make that answerable within the first sitting:
+
+- State explicitly where behavior is documented (`product/specs/`), where forward-looking design lives
+  (`product/plans/`), and where conventions live (`ai/guidelines/`) — a newcomer shouldn't have to guess
+  which directory is authoritative for which kind of question.
+- Prefer a single, current source of truth over scattered partial explanations; treat contradicting
+  or duplicated guidance across files as a bug to fix, not a style choice.
+- Recently onboarded contributors (or a fresh session with no prior context) are the best source
+  of gaps — treat a "how do I even find X" moment as a signal to fix the docs, not just answer the
+  question once and move on.
+
+## Technical specs and plans
+
+`product/plans/` holds forward-looking design docs for work not yet done (or being done), organized by
+status (`draft/`, `ready/`, `complete/`, `deferred/` — see the root `CLAUDE.md`). Unlike `product/specs/`,
+which documents current behavior, a plan documents an intended change:
+
+- Keep a plan only as detailed as needed to make the implementation decision — API/interface
+  shape and the reasoning behind a choice, not a line-by-line restatement of every ticket.
+- Cover the rejected alternatives briefly when the choice among them isn't obvious — this is what
+  saves a future reader from re-litigating a decision that was already made deliberately.
+- Move the plan file between status folders as its state changes, rather than leaving it in
+  `draft/` after the work ships — a stale plan sitting in the wrong folder misleads the next
+  person who searches there for what's actually in flight.
+- Use natural line breaks, not fixed-column wrapping, per the existing `CLAUDE.md` convention.
+
+## Record decisions, not just outcomes
+
+When a non-obvious architectural or design choice is made — and especially when an alternative was
+seriously considered and rejected — capture the *context, options considered, and consequences*,
+not just the final shape. This is the ADR (architecture decision record) pattern: it exists so a
+future contributor doesn't waste time re-deriving a rationale that already exists, or re-opening a
+question that was already closed for a reason. In this repo that reasoning belongs inline in the
+relevant spec or plan (see "Explain the 'why' inline" above) rather than in a separate decision
+log, unless a decision spans many specs and genuinely needs its own page.
+
+## Comments explain why; specs explain what and when
+
+A code comment and a spec entry serve different jobs, and neither substitutes for the other:
+
+- A **comment** belongs at the one line where the reasoning isn't recoverable from reading the
+  code itself — a workaround for a specific bug, a non-obvious constraint, why the "obvious"
+  simpler version doesn't work. This repo's own `CLAUDE.md` rule ("default to no comments; only
+  when the WHY is non-obvious") is this principle applied directly — don't restate what the code
+  already says clearly.
+- A **spec entry** belongs where a contributor needs to know the behavior *without* reading the
+  code at all — the full shape of a command, its edge cases, its error messages (see "Specs
+  describe behavior precisely" above). A spec is discoverable and structured; a comment is local
+  and easy to miss if you're not already reading that function.
+- Write both at the same time as the change, not after — the reasoning behind a decision is
+  cheapest to capture the moment it's made and gets fuzzier (or is skipped entirely) the longer
+  it's deferred.
+- An inaccurate comment or spec is worse than none: it actively misleads the next reader instead of
+  leaving them to check the code. Treat correctness here as non-negotiable, not a nice-to-have.
+
+## Keep developer docs versioned and reviewed like code
+
+- `product/specs/`, `product/plans/`, and `ai/guidelines/` all live in the same repo and are reviewed the same way
+  code is — a spec change should be part of the PR that changes the behavior it describes, not a
+  follow-up.
+- Prefer several small, focused files over one large one — the same file-size and
+  single-responsibility reasoning as [[code-guidelines]] applies to docs.
+- A stale spec is actively worse than no spec: it tells a contributor to implement or trust
+  behavior that no longer exists. Treat "the spec still matches the code" as part of the definition
+  of done for any behavior-changing PR — a reviewer should check this the same way they check that
+  tests were updated, not treat it as optional polish.
+- Docs staying next to the code they describe (`product/specs/` alongside `src/`, not in a separate wiki or
+  external tool) is what makes this checkable at review time at all — a reviewer can't be expected
+  to cross-reference a system outside the PR diff. If a doc genuinely can't live in-repo, at least
+  link to it from the PR description so review can catch drift.

package/ai/guidelines/documentation.md

@@ -0,0 +1,80 @@
+# Agent Characters in Documentation
+
+Decorative pixel-art Janissary characters appear throughout the user documentation (`documentation/user-documentation/`) as floated sprites that body text wraps around. They add visual rhythm and personality but must follow strict rules so they stay decorative rather than distracting.
+
+## Source images
+
+Agent character images live in `agent-images/` at the repo root. Each character has a subdirectory (`malik/`, `idris/`, `yusuf/`, `fariz/`, `hakim/`, `tahir/`) containing one or more character states, each with eight directional rotations. The VitePress build config (`documentation/.vitepress/config.mts`) copies the used facings into `documentation/public/agents/` at build time, trimmed and scaled — that directory is gitignored and must not be committed.
+
+## Allowed facings
+
+Only three facings are used in documentation:
+
+| Facing | Filename suffix | View description |
+|---|---|---|
+| `south` | `-south.png` | Front-facing, toward the viewer |
+| `south-east` | `-south-east.png` | Three-quarter view, turned slightly right |
+| `south-west` | `-south-west.png` | Three-quarter view, turned slightly left |
+
+**Never use `east` or `west` facings.** Those are complete side views and look flat and unnatural at the small display size used in docs. The `FACINGS` array in `config.mts` controls which rotations are copied — keep it in sync with this rule.
+
+The `north`, `north-east`, and `north-west` facings (showing the character's back) are available in `agent-images/` but not used in documentation.
+
+## The archer
+
+The animated `archer-firing.gif` is the landing-page hero image (`index.md` frontmatter). **The archer must not appear in documentation body pages.** Only the five named characters (malik, yusuf, fariz, hakim, tahir) are used as inline sprites. The idris character is not used in documentation.
+
+## Placement rules
+
+### Count per page
+
+- **1 character** on short pages (under ~30 lines)
+- **2 characters** on medium pages (~30–50 lines)
+- **3 characters** on long pages (over ~50 lines)
+
+Never place more than 3 characters on a single page, regardless of length.
+
+### Neighboring content
+
+A character sprite must be placed **only next to normal paragraph text or headings** (H1–H4). Never place a character adjacent to:
+
+- Code blocks (fenced or indented)
+- Screenshots or other images
+- Tables
+- Bullet or numbered lists
+- Blockquotes
+
+The sprite floats into the body text, so it needs flowing prose beside it to wrap naturally. A character wedged against a table or code block creates an awkward gap.
+
+### Position in the page
+
+Place the character between two block-level elements (heading + paragraph, or paragraph + paragraph, or paragraph + heading). The character tag sits on its own line with a blank line above and below:
+
+```markdown
+## Section heading
+
+<img class="agent-float" src="/agents/tahir-south-west.png" alt="" />
+
+Paragraph text that wraps around the sprite...
+```
+
+### Alternating sides
+
+Use the `left` class to float a character to the left instead of the default right. Alternate sides across a page when using multiple characters — one right, one left — so the visual weight balances. The CSS class is `agent-float left` for left-floated, `agent-float` alone for right-floated.
+
+### Vary characters across pages
+
+Don't use the same character on consecutive pages in the sidebar order when you can avoid it. Spread the five characters across the documentation so the reader sees variety.
+
+## Adding or changing a character
+
+1. Pick the character and facing from `agent-images/<name>/<state>/rotations/`.
+2. Reference it as `/agents/<name>-<facing>.png` in the markdown (the build copies it there).
+3. If you need a facing not in the `FACINGS` array in `config.mts`, add it there — the build picks it up automatically on next run.
+4. Place the `<img>` tag following the placement rules above.
+
+## Build pipeline
+
+The `copyAgentImages()` function in `config.mts` runs at VitePress config load time. For each character directory under `agent-images/`, it finds the first subdirectory (the character state), then copies each facing listed in `FACINGS` through `trimAndScaleSprite()` (which crops transparent padding and upscales 2x) before writing the result to `public/agents/<name>-<facing>.png`. The animated `archer-firing.gif` is copied as-is without trimming.
+
+Run `npm run docs:dev` to preview changes locally, or `npm run docs:build` to verify the production build.

package/ai/guidelines/human-writing-guidelines.md

@@ -0,0 +1,42 @@
+GUIDELINES FOR NATURAL, HUMAN-SOUNDING WRITING
+
+VOICE & TONE
+- Write as if addressing one specific person, not a general audience
+- Use a consistent, grounded voice — avoid a formal "presenter" tone
+- Let personality come through in word choice, not just content
+- Match formality to context; do not default to corporate-neutral language
+
+SENTENCE STRUCTURE
+- Mix short and long sentences to create natural rhythm
+- It is acceptable to start sentences with: And, But, So, Because
+- Break grammar rules intentionally when it improves clarity or tone
+- Prefer active voice; use passive voice only when intentional
+- When introducing a topic that will be broken into multiple subtopics or aspects, always lead with a forecast sentence that explicitly names or numbers the upcoming items before elaborating on each one. 
+
+WORD CHOICE
+- Use concrete, specific words instead of abstract or vague ones
+- Remove filler phrases: "It's worth noting that," "In conclusion," "It's important to remember," "It goes without saying"
+- Avoid overused AI-associated words: utilize, leverage, delve, robust, seamlessly, foster, comprehensive, multifaceted, nuanced, pivotal, transformative, holistic
+- Use contractions naturally: don't, it's, you're, we're, that's
+
+STRUCTURE & FLOW
+- Do not open by restating the question or prompt
+- Lead with the main point in the first sentence
+- Use paragraph breaks for pacing, not just topic changes
+- Write in prose when ideas connect naturally; avoid bullet points for flowing content
+
+AUTHENTICITY
+- Include mild hedging where appropriate: "probably," "I think," "in most cases," "often"
+- Acknowledge complexity without over-qualifying every statement
+- Take a clear point of view — vague or uncommitted writing feels robotic
+- Use at least one specific example or concrete detail instead of staying abstract
+- It is acceptable to leave some tension unresolved; not everything needs a tidy conclusion
+
+WHAT TO AVOID
+- Symmetrical lists that feel generated (e.g., always three examples, three counterpoints, three conclusions)
+- Closing summaries that simply restate what was already said
+- Self-announcing transitions: "Moving on to...," "Now let's discuss...," "Turning to the topic of..."
+- Excessive affirmations or enthusiasm: "Great question!", "Absolutely!", "Certainly!", "Of course!"
+- Overly polished or resolved endings — real writing sometimes ends mid-thought
+- Formulaic structure: introduction → three points → conclusion
+- avoid banned expressions: tailwind, through line

package/ai/guidelines/imports-and-barrel-files.md

@@ -0,0 +1,49 @@
+# Imports and Barrel Files
+
+Prefer **direct imports**. Import each symbol from the module that actually defines it. Do **not** introduce barrel files.
+
+A *barrel file* is a module whose only job is to re-export other modules — an `index.ts` full of `export * from './foo.js'` / `export { Bar } from './bar.js'` lines that lets callers write `import { Foo, Bar } from './feature'` instead of reaching into each file. It feels tidy. It is not worth the cost.
+
+## What to do instead
+
+```ts
+// ✅ Direct — import from the file that defines the symbol
+import { AcpLoop } from './acp/loop.js';
+import { HarnessManager } from './harness/manager.js';
+
+// ❌ Barrel — import through a re-export hub
+import { AcpLoop, HarnessManager } from './acp/index.js';
+```
+
+Relative imports keep their **`.js`** extension even though the source is `.ts` (NodeNext) — see [`../../CLAUDE.md`](../../CLAUDE.md). A direct import names a real file that "Go to Definition" jumps straight into; a barrel adds a hop that lands you in the re-export list instead.
+
+## The case against barrel files
+
+**1. They wreck tooling and build performance.** Importing one symbol through a barrel forces TypeScript, the test runner, and the bundler to load and parse *every* module the barrel re-exports — and everything those modules pull in — even though you use one of them. The whole module subtree becomes an eager dependency of anything that touches the barrel.
+
+- Atlassian removed barrel files across ~100,000 files and cut **build minutes by 75%**, made unit tests **~50% faster** locally (up to **10×** in some packages), and dropped CI unit-test counts **88%** (1,600 → 200) because far fewer files were transitively pulled into each test's graph.
+- A Next.js app that loaded **11,000+ modules** (5–10s dev startup) fell to **~3,500 modules** (a 68% reduction) after internal barrels were removed.
+
+**2. They defeat tree-shaking and inflate bundles.** Bundlers struggle to prove which re-exports through a barrel are unused, so dead code survives into production. Reported real-world drops after removing barrels: **752 kB → 186 kB** (Angular) and **1.5 MB → 200 kB** (Next.js). A barrel stops being tree-shakeable the moment it contains anything other than pure re-exports — even one `export const x = 5` introduces a possible side effect and disables the optimization.
+
+**3. They breed circular dependencies.** When a file imports from the barrel of its *own* directory, it depends on a module that re-exports itself — a cycle. These often work in dev and break in production, or work under one bundler and crash under another, with cryptic errors. Direct imports between siblings (`./loop.js` importing `./manager.js`, never `./index.js`) avoid the loop entirely.
+
+**4. They degrade day-to-day DX.** "Go to Definition" lands in the barrel instead of the implementation. Diffs and blame get noisier. The real dependency graph is hidden behind a hub, so it's harder to see what actually depends on what — the opposite of what a namespace directory is supposed to give you.
+
+## The one legitimate exception: a package's public API
+
+A barrel is appropriate as the **single published entry point of a library** — the module named by a package's `exports`/`main`, drawing a deliberate boundary between public API and internals. That is a *public surface* decision, made once at a package edge.
+
+This codebase is an application, not a published library. We have no such boundary to draw, so we have no reason for barrels. When we group files into a namespace directory (see [`../tasks/improve-namespacing.md`](../tasks/improve-namespacing.md)), callers import the specific file inside it (`./acp/loop.js`), not a `./acp/index.js` hub. **Do not create an `index.ts` barrel where none existed.** The improve-namespacing task only ever converts an *already-existing* bare entry file (e.g. `src/acp.ts`) into `src/acp/index.js`; it never invents a new one.
+
+**Rule.** Import every symbol directly from its defining module, with the `.js` extension. Never add a barrel/`index.ts` re-export hub to application code. A namespace is a directory of directly-imported files — not a directory fronted by a re-export index.
+
+---
+
+Sources:
+
+- [tkdodo.eu — Please Stop Using Barrel Files](https://tkdodo.eu/blog/please-stop-using-barrel-files)
+- [Atlassian Engineering — How We Achieved 75% Faster Builds by Removing Barrel Files](https://www.atlassian.com/blog/atlassian-engineering/faster-builds-when-removing-barrel-files)
+- [DEV — Barrel files and why you should STOP using them now](https://dev.to/tassiofront/barrel-files-and-why-you-should-stop-using-them-now-bc4)
+- [Vercel/Next.js — Tree shaking doesn't work with TypeScript barrel files (#12557)](https://github.com/vercel/next.js/issues/12557)
+- [laniewski.me — Why you should avoid Barrel Files in JavaScript Modules](https://laniewski.me/blog/pitfalls-of-barrel-files-in-javascript-modules/)