ai-collab-open-system 0.1.0

package/docs/FEEDBACK.md

@@ -0,0 +1,61 @@
+# Feedback
+
+Tried the workspace? Tell us what actually happened. This is the main feedback entry point. If you came from the [Dogfood Guide](./DOGFOOD.md), this is where you land.
+
+**How to send it:**
+
+- Open a GitHub issue using the **Dogfood feedback** template (under `.github/ISSUE_TEMPLATE/`), or
+- Copy the form below into a new issue / discussion and fill it in.
+
+**One rule, read it first:** report your **experience**, never your **material**. Every field below asks for how it felt or what you noticed — not the task you ran, not the work you reviewed. Do not paste real task content, customer or contact material, tokens or credentials, absolute local paths, private chat logs, or company-internal information into any field. If you want to illustrate something, rewrite it as a synthetic placeholder or describe it in words. We do not collect your private originals — the open method runs entirely on your own machine. Full list: [What NOT to upload](./DOGFOOD.md#what-not-to-upload).
+
+中文（同义）：只反馈体验感受，不要贴真实材料。下面每个字段都只问"感觉如何、注意到什么"，不要把真实任务内容、客户或联系人信息、密钥口令、本机绝对路径、私有对话原文、公司内部信息填进去。要举例就改写成合成占位例子或用文字描述。我们不收集你的私有原文，开源方法在你自己机器上就完整可用。
+
+---
+
+## Feedback form
+
+Copy this block into an issue or discussion and fill it in. Leave a field blank if it does not apply.
+
+```text
+1. Which AI tools do you use?
+   (e.g. Claude Code / Codex / Cursor / Copilot / Cline / Windsurf / a chat AI — names of TOOLS only)
+
+2. What was your original pain point?
+   (context loss / AI claiming false completion / re-explaining background across sessions /
+    not knowing which AI is right / something else)
+   --> Describe the PAIN, not the task it happened on.
+
+3. Where did the first experience stall, if it did?
+   (which step of the 10-minute or 30-minute path, what was unclear or broke)
+   --> Describe the STEP and what confused you, not the content you fed in.
+
+4. Which mechanism was the most useful?
+   (e.g. dual-guard / handoff / acceptance / harvest / ... — and one line on why)
+
+5. Which mechanism did you NOT understand?
+   (which one read as jargon, where you got lost — this is the most useful thing you can tell us)
+
+6. Would you use this on a real workflow?
+   (yes / no / maybe — and the one thing that would tip it)
+   --> Your YES/NO and the blocker, not a description of the real workflow itself.
+
+7. Would paying to save calibration time be worth it to you?
+   (yes / no / not sure — this is just to gauge interest; no numbers, no commitment)
+
+8. Anything else?
+   (one thing that surprised you, one thing that annoyed you)
+
+Privacy check:
+[ ] Every answer above is about my EXPERIENCE, not my actual task content.
+[ ] I included no customer or contact material, tokens, credentials, absolute local paths,
+    private chat logs, or company-internal information.
+```
+
+---
+
+## What we do with it
+
+- **Confusion is a bug.** If a step stalled or a mechanism read as jargon, that is the kind of report that actually fixes the open system. We would rather hear "I got lost at step 3" than nothing.
+- **Interest in paid help is just a signal.** Question 7 only gauges whether tuned-for-you help would be wanted. The open method stays complete and free either way — paid help is calibration / setup / migration / review / pairing, never unlocking the basics. See [docs/FREE_VS_PAID.md](./FREE_VS_PAID.md).
+- **We never collect private content.** This project is local-first by design. If a field ever tempts you to paste something private, stop and describe it in words instead — that is always enough for us to act on.

package/docs/FIRST_EXPERIENCE_SPEC.md

@@ -0,0 +1,32 @@
+# First Experience Spec
+
+## Required Path
+
+```text
+install or clone
+-> initialize workspace
+-> open START_HERE.md
+-> choose a 10 / 30 / 60 minute path
+-> run one complete synthetic task loop
+-> adapt the same workspace to a real task
+```
+
+## README first screen
+
+The first screen must say this is an open-source personal AI collaboration workspace and point to `START_HERE.md`.
+
+## CLI help
+
+CLI help must show:
+
+```text
+init -> open START_HERE.md -> choose 10 / 30 / 60 minute path -> run one synthetic loop
+```
+
+## Init output
+
+Init output must print the generated workspace path, the `START_HERE.md` path, and `Network: not used`.
+
+## Completion evidence
+
+The contract is not satisfied by positioning copy alone. A generated workspace and at least one synthetic loop artifact chain must exist.

package/docs/FREE_VS_PAID.md

@@ -0,0 +1,53 @@
+# Free vs Paid
+
+The short version: **the open method is complete and free. Paid help is only a service — calibration, setup, migration, review, pairing — that saves you time. Nothing in the method is hidden behind payment.**
+
+This is the project's honesty line, and it is the whole point. We never communicate "you have a problem, pay to see the answer."
+
+## Free and open (the complete method)
+
+Everything you need to run the full collaboration loop yourself, with no part held back:
+
+- Complete generic workspace generation (the whole `.aict/` skeleton).
+- `START_HERE.md` and the 10 / 30 / 60-minute walkthroughs.
+- Six collaboration layers (profile, context, acceptance, guard review, handoff, harvest) — each with prompt, template, synthetic example, and failure modes.
+- All 16 mechanism packages (dual guard, SCOUT review controller, one-click dispatch, task splitting, anti-drift partner, blind-spot scan, root-cause brake, half-product review, handoff A/B/C, harvest and external recap, do-not-handle-yet, plain-language first screen, honest calibration, feedback-absorption ledger, collaboration coach, single-tool guard).
+- The full prompt library.
+- All skill-like files.
+- The cookbook recipes.
+- Thin adapters for Claude Code, Codex, Cursor, Windsurf, Copilot, and Cline.
+- The synthetic full-loop cases.
+- Privacy and commercial-boundary docs.
+- Contract, privacy, and pack checks.
+
+No mechanism, template, role, mode, prompt, or recipe is reserved for a paid tier. If it is part of the method, it is in the open package. There is no "pro mechanism", no locked guard, no premium prompt.
+
+## Paid help (a service, not a key)
+
+If — and only if — you want the generic system tuned to *your* tools and *your* workflow, paid help may offer:
+
+- **Calibration** — adjusting thresholds, profile, and guard rules to fit your actual tools and habits.
+- **Setup** — building your workspace with you, wired to your own project.
+- **Migration** — moving you over from your existing AI workflow into this structure.
+- **Review** — an outside pass on your collaboration flow, or async audit of how you run it.
+- **Pairing** — working alongside you through a real loop or two.
+- **Saving calibration time** — in one line, you pay to skip the trial-and-error of tuning it yourself, not to obtain anything the open package lacks.
+
+Each of these is a service performed *on top of* the open method, with you, on your own complete system. You could do all of it yourself with the open package; paid help just does it faster and for your specific setup.
+
+## The boundary (the honest line)
+
+The method is public and complete. Paid help calibrates it to a real workflow and saves the time of trial and error. It must never unlock the basic method, and it must never be framed as the only way to get the real answer.
+
+| Framing | Allowed? | Why |
+| --- | --- | --- |
+| "The method is open and complete. Paid help calibrates it to your workflow and saves you time." | **Yes** | True, and respects that you already have everything you need. |
+| "The open version only tells you the problem; pay to get the fix." | **No** | False — the fix *is* the open method. This is the paywall-the-answer pattern we refuse. |
+| "Pay to unlock the real mechanisms / the pro guard / the premium prompts." | **No** | There is no locked tier. Every mechanism ships in the open package. |
+| "Run the doctor; it found problems; buy help to solve them." | **No** | The health check is a secondary, optional helper, never a conversion funnel. See [PRODUCT_CONTRACT.md §5](../PRODUCT_CONTRACT.md). |
+
+If you read the open package and decide you never need paid help, that is a success, not a failure. The project did its job.
+
+This boundary is enforced as a contract, not just a promise: see [PRODUCT_CONTRACT.md §7](../PRODUCT_CONTRACT.md) (Commercial Boundary) and the validate-contract check.
+
+中文（同义）：开源方法是完整的、免费的，所有机制 / 模板 / 角色 / 模式 / cookbook 都在开源包里，不阉割、不留付费墙。付费只卖"服务"——校准（把阈值调到适配你的工具）、代搭、迁移、审查、陪跑、帮你省下自己摸索调参的时间。绝不暗示"你有问题、付费才给答案"。看完开源包觉得不需要付费，那就是成功。

package/docs/PUBLIC_BOUNDARY.md

@@ -0,0 +1,36 @@
+# Public Boundary
+
+## Publish
+
+- Generic architecture.
+- Generic prompts.
+- Generic templates.
+- Thin adapters.
+- Synthetic examples.
+- Setup guides.
+- Privacy docs.
+- Known limitations.
+
+## Do Not Publish
+
+- Private governance contents.
+- Private knowledge-base source material.
+- Real personal profile.
+- Actual client material.
+- Raw private conversations.
+- Non-public automation or routing details.
+- Internal calibration thresholds.
+- Internal scoring weights.
+- Account-specific habits.
+- Local machine paths.
+- Tokens, keys, cookies, or credentials.
+- Unredacted screenshots.
+- Full internal service SOP.
+
+## Test
+
+Run:
+
+```bash
+node scripts/privacy-scan.js
+```

package/docs/PUBLIC_MAPPING.md

@@ -0,0 +1,178 @@
+# Public Mapping — a good-faith open-source ledger
+
+This document is the honest account of how a private collaboration system was turned into this public edition. It is a safety map, not a source dump — but it is written so a stranger can verify that the desensitization preserved a usable method instead of gutting it into marketing.
+
+The short version: **the thinking and the structure are public. Only the private fuel is removed, and where something is removed you are given a synthetic equivalent you can actually run.** This is meant to be real open source, not a teaser.
+
+## How to read this ledger
+
+Below is one row per **class of published asset**. Each row answers seven questions:
+
+1. **Source idea** — the core idea the asset encodes (the part worth keeping).
+2. **Public artifact** — which files or directories carry it in this repo.
+3. **Kept verbatim (Y/N)** — whether the structure, templates, and reasoning are published unchanged.
+4. **Rewritten / desensitized (Y/N)** — whether anything was redacted, and exactly what.
+5. **Cannot be published** — the private parts that never enter this repo, and why.
+6. **Public-safe equivalent** — what you get instead of the removed parts, so the method still works.
+7. **File evidence** — concrete paths you can open and check against these claims.
+
+If a row says **kept verbatim: Y**, open the file evidence and you should find the real structure, not a paraphrase. If a row says **desensitized: Y**, the public-safe-equivalent column tells you what generic version replaced the private fuel — never just "rewritten," always "rewritten into *this*, and here is why it is still useful."
+
+## Our desensitization principles
+
+These are the rules the rewrite followed. The full boundary is in `../PRODUCT_CONTRACT.md` §6.
+
+- **Keep the method, drop the fuel.** The reusable part of a mechanism is its idea, structure, prompt, template, and pass/reject bar. Those are kept verbatim. The fuel — a real person's profile, real client work, raw conversations, calibration numbers — is what makes it private, so the fuel is removed and the method stays.
+- **Every removal earns an equivalent.** When private numbers or transcripts are pulled, they are replaced with a synthetic equivalent that does the same job: a definitional binding strength instead of a measured percentage, a worked synthetic run instead of a real one, an example threshold you re-tune to your own tools instead of someone else's tuned value. Desensitization is a swap, not a deletion.
+- **The redaction question.** Every public example had to pass one test (`PRODUCT_CONTRACT.md` §6.3): *could a stranger infer the owner's private system, identity, clients, files, habits, or routes from this?* If yes, it was rewritten as a synthetic example before it was allowed in.
+- **A machine gate, not a promise.** The boundary is not enforced by good intentions. `scripts/privacy-scan.js` hard-blocks local paths, the private governance path, the private knowledge system, private hook references, tokens, keys, and emails — and it scans this ledger too. The principle "key rules are machine-enforced, not left to self-discipline" is itself a published idea (last row), even though the private enforcement internals are not.
+
+---
+
+## The ledger
+
+### Asset class 1 — The six-layer file workspace (profile / context / acceptance / guard / handoff / harvest)
+
+| Column | Account |
+| --- | --- |
+| **Source idea** | Local-first and file-based: instead of holding collaboration state in chat memory, externalize it into reviewable files a human can open, diff, and audit. State you can see is state you can govern. |
+| **Public artifact** | The six layer directories, each with the same five-file shape (`README.md`, `PROMPT.md`, `TEMPLATE.md`, `EXAMPLE.synthetic.md`, `FAILURE_MODES.md`). |
+| **Kept verbatim (Y/N)** | **Y** — the layer structure, the blank templates, and the prompts are published unchanged. The skeleton is the asset, and the skeleton is real. |
+| **Rewritten / desensitized (Y/N)** | **Y** — every `EXAMPLE.synthetic.md` is fully synthetic. No real profile, no real task context, no real acceptance trail. |
+| **Cannot be published** | The owner's real personal profile, real client requirements, raw private chats, account-specific habits, and machine-local paths. These are exactly the fuel that would let a stranger reconstruct a private system. |
+| **Public-safe equivalent** | Blank templates you fill with **your own** profile and tasks, plus synthetic filled examples that show the shape without copying anyone's life. The workflow value survives the absence of the private source. |
+| **File evidence** | `.aict/profile/`, `.aict/context/`, `.aict/acceptance/`, `.aict/guard/`, `.aict/handoff/`, `.aict/harvest/` |
+
+### Asset class 2 — Dual Guard
+
+| Column | Account |
+| --- | --- |
+| **Source idea** | Cancel a single AI's shared blind spot with **structure, not a stronger model**: a guard from a different model family is the binding gate; a same-family guard is a non-binding reference. A fluent answer is not trusted just because it reads well. |
+| **Public artifact** | The full mechanism package, deepened to nine elements (purpose, when / when-not, input shape, process, output shape, pass bar, reject bar, common misuse, package files). |
+| **Kept verbatim (Y/N)** | **Y** — the idea, the layered-strictness merge rule ("not a vote; one evidence-grounded blocker rejects"), the process steps, and the pass/reject bars are published as-is. |
+| **Rewritten / desensitized (Y/N)** | **Y** — the real **binding-strength numbers were removed**. Private "how often each family misses" percentages and calibration data are replaced with a qualitative statement: cross-family = the gold-standard binding pass; same-family = reference only. |
+| **Cannot be published** | Real miss-rate percentages, internal calibration datasets, and any private scoring weights that backed the original tuning. |
+| **Public-safe equivalent** | A definitional experience range you can act on (same-family reviewers tend to miss the same things; a different family catches more), plus a fully worked synthetic run — a synthetic task board, "family X" drafts and "family Y" binds — that demonstrates the gate without a single private number. |
+| **File evidence** | `.aict/mechanisms/dual-guard/` (`README.md`, `EXAMPLE.synthetic.md`, `FAILURE_MODES.md`) |
+
+### Asset class 3 — Task splitting
+
+| Column | Account |
+| --- | --- |
+| **Source idea** | Before handing a large job to another AI, split it so each piece is self-contained and small enough not to overflow the tool's working window — prevention by splitting, not recovery after a stall. |
+| **Public artifact** | The mechanism package, including the pre-dispatch self-audit. |
+| **Kept verbatim (Y/N)** | **Y** — the self-audit checklist and the "split by topic/segment, keep each piece self-contained" rule are published unchanged. |
+| **Rewritten / desensitized (Y/N)** | **Y** — the **real tuned numeric thresholds were removed** and relabeled as example thresholds you re-tune to your own tool's context window. |
+| **Cannot be published** | The owner's specific tuned trigger values, which are calibrated to private tooling and would leak operational detail. |
+| **Public-safe equivalent** | An operational set of self-audit questions with **example** values clearly marked "adjust to your tool," so you get a working procedure instead of someone else's machine-specific constants. |
+| **File evidence** | `.aict/mechanisms/task-splitting/` |
+
+### Asset class 4 — Handoff (A / B / C three modes)
+
+| Column | Account |
+| --- | --- |
+| **Source idea** | Hand a task between sessions or tools by carrying explicit state, not chat memory — with three handoff modes for three situations (A high-interaction / B programmatic / C delivery overview) that all carry the same fixed set of must-include fields so the next session starts cleanly. |
+| **Public artifact** | The mechanism package with the three-mode model and required-field list. |
+| **Kept verbatim (Y/N)** | **Y** — the A/B/C modes and the required-field structure are published as-is; that structure is the whole point. |
+| **Rewritten / desensitized (Y/N)** | **Y** — example session identifiers and paths are synthetic. |
+| **Cannot be published** | Real session ids and real machine-local paths from actual handoffs. |
+| **Public-safe equivalent** | A synthetic end-to-end handoff example (made-up session, made-up next-step) that shows exactly which fields to fill, without exposing a real session. |
+| **File evidence** | `.aict/mechanisms/handoff-abc/` |
+
+### Asset class 5 — Harvest and ERC
+
+| Column | Account |
+| --- | --- |
+| **Source idea** | Turn a working conversation into durable knowledge through a fixed pipeline — scan → card → desensitize → confirm → file — and gate the cross-session "external recap" role behind a two-lock entry so it cannot start by accident. |
+| **Public artifact** | The mechanism package with the harvest pipeline and the ERC two-lock entry. |
+| **Kept verbatim (Y/N)** | **Y** — the scan→card→desensitize→confirm→file pipeline and the two-lock entry condition are published unchanged. |
+| **Rewritten / desensitized (Y/N)** | **Y** — the worked harvest card is synthetic. |
+| **Cannot be published** | Real harvested content (it would be private strategy, business, or growth material from actual sessions). |
+| **Public-safe equivalent** | A synthetic harvest-card example that demonstrates the pipeline end to end, so you can run the same flow on your own conversations. |
+| **File evidence** | `.aict/mechanisms/harvest-and-erc/` |
+
+### Asset class 6 — The role system
+
+| Column | Account |
+| --- | --- |
+| **Source idea** | Split collaboration into named roles with an explicit authority matrix — who proposes, who executes, who guards, who gathers facts, who harvests — so no single agent silently does everything. |
+| **Public artifact** | Five role cards plus a roles README, written as a responsibility matrix. |
+| **Kept verbatim (Y/N)** | **Y** — the responsibility-matrix structure and the role boundaries are published unchanged. |
+| **Rewritten / desensitized (Y/N)** | **Y** — specific private product names were **replaced with generic terms**: a "main-brain AI," an "execution AI," and "different model families," instead of named tools and private internal routing. |
+| **Cannot be published** | The owner's private authority structure tied to specific tools, and tool-specific internal routing. |
+| **Public-safe equivalent** | Generic, vendor-neutral role cards (owner-controller / executor / guardian / scout / harvester) that map onto any tool stack, so the boundaries transfer without naming a private setup. |
+| **File evidence** | `.aict/roles/` (`owner-controller.md`, `executor.md`, `system-guardian.md`, `scout.md`, `harvester.md`, `README.md`) |
+
+### Asset class 7 — The mode system
+
+| Column | Account |
+| --- | --- |
+| **Source idea** | Run collaboration in explicit modes (execute / review / handoff / harvest) with defined entry, exit, and cross-mode handoff, so the system always knows which posture it is in. |
+| **Public artifact** | Four mode cards plus a modes README. |
+| **Kept verbatim (Y/N)** | **Y** — the entry / exit / handoff structure of each mode is published unchanged. |
+| **Rewritten / desensitized (Y/N)** | **N (structure)** — the mode mechanics are generic and need no redaction; any illustrative content is synthetic. |
+| **Cannot be published** | Nothing mode-structural is private. (Private *content* that might pass through a mode is handled by the other asset classes' redaction.) |
+| **Public-safe equivalent** | The mode cards themselves are already the public-safe form — generic postures usable on any stack. |
+| **File evidence** | `.aict/modes/` (`execute.md`, `review.md`, `handoff.md`, `harvest.md`, `README.md`) |
+
+### Asset class 8 — The mistake log / failure modes
+
+| Column | Account |
+| --- | --- |
+| **Source idea** | Distill real incidents into anti-recurrence rules — every accident becomes a named failure mode so it does not happen twice. |
+| **Public artifact** | A `FAILURE_MODES.md` alongside each layer and each mechanism. |
+| **Kept verbatim (Y/N)** | **Y** — the method (incident → named failure mode → guard against it) is published unchanged. |
+| **Rewritten / desensitized (Y/N)** | **Y** — the **real incident write-ups are not published**; the failure modes are reconstructed as synthetic, generic failures. |
+| **Cannot be published** | Actual private feedback entries, which would describe real sessions, real mistakes, and real context. |
+| **Public-safe equivalent** | The distillation method plus synthetic failure modes that name the same traps (e.g. treating a guard pass as a vote, skipping the gate on "looks fine" work) without exposing where they were learned. |
+| **File evidence** | `.aict/mechanisms/dual-guard/FAILURE_MODES.md` and the other `FAILURE_MODES.md` files under `.aict/mechanisms/` and the six layers |
+
+### Asset class 9 — The flagship case study (and the other synthetic labs)
+
+| Column | Account |
+| --- | --- |
+| **Source idea** | Show the whole system on one realistic long task — an AI-coding job carried from request to a guarded "done" — so the mechanisms are seen working together, not just described. |
+| **Public artifact** | The flagship case plus four more synthetic labs, each with a `CASE.md` and supporting artifacts. |
+| **Kept verbatim (Y/N)** | **Y (shape)** — the case structure (request → execution → review → verdict → residual risk) is real and complete. |
+| **Rewritten / desensitized (Y/N)** | **Y** — every case is **fully synthetic**: a fictional task board, not a real project. |
+| **Cannot be published** | Real source code, real projects, real customers, or real source conversations. |
+| **Public-safe equivalent** | A synthetic-but-realistic reviewed artifact — invented code and an invented task whose review still exercises real acceptance criteria — so the demonstration is honest about being synthetic while still teaching the loop. |
+| **File evidence** | `.aict/examples/ai-coding-long-task/` (`CASE.md`, `artifacts/`) and the four sibling labs under `.aict/examples/` |
+
+### Asset class 10 — Machine gates and format locks (the idea, not the implementation)
+
+| Column | Account |
+| --- | --- |
+| **Source idea** | Key rules must be **machine-enforced, not left to self-discipline** — a soft instruction a model can rationalize away is weaker than a gate that hard-blocks. This *philosophy* is publishable even though the private enforcement is not. |
+| **Public artifact** | One concrete, public-safe gate (`scripts/privacy-scan.js`) plus the privacy docs that state the principle. |
+| **Kept verbatim (Y/N)** | **Y (principle)** — the idea "machine-enforce the rules that matter" is stated plainly. |
+| **Rewritten / desensitized (Y/N)** | **Y** — the **specific private hook implementations, routing, and thresholds are not published**; only a lightweight public gate is. |
+| **Cannot be published** | The private hook code and paths, the internal routing logic, and the tuned thresholds — the operational guts that would leak how the private system is wired. |
+| **Public-safe equivalent** | A real, runnable lightweight gate (`privacy-scan.js`) you can read and use, proving the principle is genuine and not vaporware, without shipping the private enforcement internals. |
+| **File evidence** | `scripts/privacy-scan.js`, `../PRODUCT_CONTRACT.md` §6, `.aict/privacy/` |
+
+---
+
+## Summary in the contract's own terms
+
+These are the boundary terms from `PRODUCT_CONTRACT.md` §6, restated so this ledger is searchable against the contract.
+
+### Public asset
+
+The public asset across every row is the **reusable mechanism shape**: ideas, structures, prompts, templates, acceptance cards, guard reviews, handoffs, harvest seeds, roles, modes, and synthetic labs. That shape is published, in most rows verbatim.
+
+### Rewritten
+
+Private fuel is **rewritten** into public-safe equivalents — never simply dropped. A rule is published only when it can be explained without exposing private source material, and when it can, the explanation is kept whole.
+
+### Cannot be published
+
+The following never enter this repo: real personal profiles, raw conversations, actual customer or project details, **non-public automation** hooks, non-public routing, hidden thresholds, internal calibration numbers, internal weights, account clues, tokens, and local machine paths.
+
+### Public-safe equivalent
+
+For every removal there is a **public-safe equivalent**: synthetic labs, generic mechanism packages, blank templates you fill yourself, definitional binding strengths in place of measured numbers, and explicit privacy boundaries. The value stays usable even when the private source is absent — that is the whole point of a ledger instead of a deletion list.
+
+### Synthetic cases
+
+All public examples are **synthetic cases**. They preserve workflow value without copying private source material, and they say so on their face. If a stranger reads this ledger and then opens the file evidence, the two should agree — that agreement is the proof that this is real open source.

package/docs/RELEASE_PRIORITY.md

@@ -0,0 +1,23 @@
+# Release Priority
+
+## P0
+
+- Generate a complete `.aict` workspace.
+- Keep `START_HERE.md` as the first path.
+- Include all six layers with prompt, template, example, and failure modes.
+- Include five synthetic cases.
+- Keep adapters thin and pointed to one shared core contract.
+- Run contract and privacy checks.
+
+## P1
+
+- Improve bilingual polish.
+- Add more synthetic transcripts.
+- Add packaging checks.
+- Add usability notes from real readers.
+
+## P2
+
+- Add optional scenario packs.
+- Add more adapters if tools introduce stable instruction formats.
+- Add richer contribution guides.

package/docs/WHY_THIS_EXISTS.md

@@ -0,0 +1,36 @@
+# Why This Exists
+
+Most advice for getting more out of AI is "use a better model." It helps, then it hits a ceiling — because model capability is only one factor in how productive you actually are.
+
+## The productivity formula
+
+    AI productivity = model capability
+                   × personal profile
+                   × context management
+                   × collaboration protocol
+                   × judgment loop
+                   × distribution / harvest flywheel
+
+It is a **product, not a sum**, and that is the whole point. If any one factor is near zero, the result is near zero no matter how large the others are. A frontier model with no definition of "done", no second pass to catch a false completion, no handoff, and nothing harvested for next time still produces unreliable, un-compounding work. That is the mathematical reason "just switch to a stronger model" stops paying off: you cannot multiply your way past a factor that is zero.
+
+It is also why this is **not a luck machine**. It does not try to make AI magically right more often. It raises the other five factors so the capability you already pay for actually lands.
+
+## What the open version gives you
+
+You bring the model — Claude, Cursor, Codex, whatever you already use. This workspace provides the other five factors:
+
+- **Personal profile** — your AI keeps up with your current situation and preferences, so each round of work lands closer to what you actually want.
+- **Context management** — a boundary and an acceptance card, so a task has a definition of "done" before work starts.
+- **Collaboration protocol** — guard reviews, single-tool or cross-family checks, and a coaching layer that reminds you to use them at the right moment.
+- **Judgment loop** — a "done" claim has to prove itself with evidence before you trust it.
+- **Distribution / harvest flywheel** — what you work out once becomes a reusable card instead of vanishing when the chat ends.
+
+## A personal AI operating system
+
+Think of it less as a prompt pack and more as an operating system for working with AI: a small set of explicit files — profile, context, acceptance, guard, handoff, harvest — that any tool can load, so your standards travel with you across tools and across days instead of living in one chat history that disappears tomorrow.
+
+## Where it comes from
+
+This is extracted from a long-running, real personal AI-collaboration practice — not a clean-room theory. The thresholds, the failure cases, and the strong opinions are kept; the private details are stripped out. What is left is the part that generalizes: the structure, the numbers that actually matter, and the hard-won "don't do this" lessons.
+
+The open method is complete enough to run on your own. If paid help is ever offered, it only calibrates this generic system to your real tools and workflow — it never unlocks a hidden version.

package/docs/open-system/00-start-here.md

@@ -0,0 +1,60 @@
+# 00 Start Here - AI Collaboration Open System
+
+AI Collaboration Open System is a local-first way to make AI work visible, reviewable, handoff-ready, and reusable. Start by running the CLI, not by reading the whole theory.
+
+This package is not published to npm yet, so run the CLI from a clone with `node bin/ai-collab.js`. The global `ai-collab` command only works after publish.
+
+## 10 minutes
+
+This is the first-run path, consistent with the README and START_HERE: two ways in, with **Path 1 (run the loop on your own real task) recommended** and the prepared demo as the optional Path 2.
+
+```bash
+node bin/ai-collab.js init --target ./my-ai-workspace
+node bin/ai-collab.js check --workspace ./my-ai-workspace
+```
+
+(The package is not on npm yet, so use the local CLI entry `node bin/ai-collab.js`; after the npm package ships, the same commands run under the global `ai-collab` name. You can also run `node bin/ai-collab.js demo` to generate a throwaway synthetic workspace and inspect it.)
+
+**Path 1 (recommended) — your own task:** open `./my-ai-workspace/.aict/walkthroughs/10-minute-your-task.md` and follow its five steps on one real (lightly redacted) task: the AI returns a boundary card and an acceptance card (done defined before any work), does only the accepted slice, then a fresh chat re-checks the result against evidence and rejects a claim the evidence does not back.
+
+**Path 2 (optional) — watch the prepared demo first:** if your task feels too sensitive to paste, open `./my-ai-workspace/.aict/walkthroughs/10-minute.md` instead; it walks you through the flagship synthetic lab at `examples/ai-coding-long-task/CASE.md` and its artifacts, then catches a planted false "done". After it, run Path 1 on your own task.
+
+The workspace map is `./my-ai-workspace/.aict/START_HERE.md`.
+
+## Why this is not a prompt pack
+
+A prompt pack gives you better one-off instructions. This system gives you a workspace with state: profile, context, acceptance, guard, handoff, harvest, roles, modes, mechanisms, cookbook, examples, and local state files.
+
+## Why it is steadier than a single-agent chat
+
+A single-agent chat can sound confident while losing rejected scope, missing evidence, and forgetting what is unverified. The local-first OS keeps those things in files:
+
+- Context names the task boundary.
+- Acceptance defines done before work starts.
+- Guard review challenges the output before trust.
+- Handoff lets another session resume.
+- Harvest keeps the reusable lesson.
+
+## The two paths in steps
+
+This restates the 10-minute paths above, in steps. Path 1 is the recommended on-ramp; Path 2 is the optional demo.
+
+**Path 1 (recommended) — run the loop on your own real task:**
+
+1. Run `node bin/ai-collab.js init --target ./my-ai-workspace`.
+2. Open `./my-ai-workspace/.aict/walkthroughs/10-minute-your-task.md` and follow its five steps.
+3. Describe one real (lightly redacted) task; the AI returns a boundary card and an acceptance card — done defined before any work.
+4. Let it do only the accepted slice and report what it changed, ran, and did not verify.
+5. Open a fresh chat (ideally a different AI family) and have it re-check the result against evidence — watch it pressure-test the "done" claim and either pass it, reject it, or flag insufficient evidence, depending on what the evidence shows rather than the tone.
+
+**Path 2 (optional) — watch the prepared demo first:**
+
+1. Run the same `init` as above.
+2. Open `./my-ai-workspace/.aict/walkthroughs/10-minute.md` and follow its five steps; optionally run `node bin/ai-collab.js demo` to inspect a throwaway synthetic workspace.
+3. It walks you through the flagship case `examples/ai-coding-long-task/CASE.md` and its artifacts.
+4. Copy the context package, acceptance card, and execution prompt into Codex, Claude Code, Cursor, Cline, Windsurf, or Copilot.
+5. Run guard review before accepting the answer and watch it catch the planted false "done" — then come back and run Path 1 on your own task.
+
+## Next file
+
+Read `01-ai-collaboration-os.md` after you have run your first loop.

package/docs/open-system/01-ai-collaboration-os.md

@@ -0,0 +1,33 @@
+# 01 AI Collaboration OS
+
+AI Collaboration Open System is a local-first collaboration operating system for people who use AI tools but do not want the tool to become the center of judgment.
+
+## Core idea
+
+The system does not try to automate all agents. It keeps the human in the controller seat and gives every AI tool the same visible state:
+
+- Who is this work for?
+- What is the task boundary?
+- What does done mean?
+- What evidence exists?
+- What must be reviewed before trust?
+- What should the next session know?
+- What reusable learning should be saved?
+
+## What runs locally
+
+The CLI writes plain files into `.aict/`. It does not call model APIs, upload content, or run telemetry. Your AI tool can read the files you choose to paste or attach.
+
+## Operating loop
+
+1. Profile sets collaboration defaults.
+2. Context packages the task.
+3. Acceptance defines pass and reject states.
+4. Execution creates the artifact.
+5. Guards challenge evidence, scope, and privacy.
+6. Handoff transfers state.
+7. Harvest saves reusable knowledge.
+
+## Public edition boundary
+
+The public edition includes generic mechanisms, templates, prompts, roles, modes, and synthetic labs. It excludes private personal profiles, non-public automation hooks, account material, raw chats, and any real client or identity trail.

package/docs/open-system/02-six-layer-architecture.md

@@ -0,0 +1,45 @@
+# 02 Six-Layer Architecture
+
+The AI Collaboration Open System uses a local-first six-layer architecture. Each layer answers one question and produces one inspectable artifact.
+
+## 1. Profile
+
+Question: how should AI collaborate with this person or team?
+
+Output: stable working preferences, decision style, boundaries, and review preferences.
+
+## 2. Context
+
+Question: what is the current task, and what should not be assumed?
+
+Output: goal, state, artifacts, facts, assumptions, risks, non-goals, and open questions.
+
+## 3. Acceptance
+
+Question: what does done mean before work starts?
+
+Output: deliverables, pass criteria, required checks, rejected states, and evidence needed.
+
+## 4. Guard
+
+Question: what must be challenged before trust?
+
+Output: findings, evidence, required fixes, residual risk, and recommendation.
+
+This is the single review layer (`.aict/guard/`). When work needs two independent review passes, use the dual-guard mechanism in `.aict/mechanisms/dual-guard/`.
+
+## 5. Handoff
+
+Question: how can the next session continue without replaying the whole chat?
+
+Output: done, pending, blocked, unverified, decisions, verification evidence, and next action.
+
+## 6. Harvest
+
+Question: what reusable learning should survive this task?
+
+Output: reusable knowledge, prompt fragments, decision records, rule candidates, and what not to generalize.
+
+## Why files matter
+
+Single-agent chats hide state in the conversation. A local-first workspace keeps state in files that can be reviewed, copied, corrected, and handed to any AI tool.

package/docs/open-system/03-role-system.md

@@ -0,0 +1,33 @@
+# 03 Role System
+
+The AI Collaboration Open System uses roles to separate responsibility. Roles are public-safe collaboration boundaries, not secret authority.
+
+Each role is defined as a responsibility matrix rather than a two-line "does / does not". A matrix states six things — what the role **can do**, what it **cannot do**, what it takes **in**, what it produces **out**, who it **escalates to** when something exceeds its authority, and a concrete **overreach example** of what breaks when the boundary is crossed. The full role cards live in `.aict/roles/`; the summaries below mirror them.
+
+## Owner / controller
+
+Top of the responsibility chain. **Can:** set the goal and acceptance, issue instructions, choose between options, accept or reject work, and own the final decision. **Cannot:** approve its own judgment as if it were independent review, make the guardian's call, or step in to do the heavy production work that should have been delegated. **In:** the task plus proposed plans, options, returned artifacts, and verdicts. **Out:** instructions, acceptance decisions, and the final recorded decision. **Escalates to:** no one above it — it tasks a scout for facts or a guardian for a check, but never hands the decision upward. **Overreach:** if the controller writes the implementation itself, no independent party is left to review it, so it grades its own homework and a defect ships.
+
+## Executor
+
+**Can:** implement the task from the provided files, change the agreed artifacts, save state, and self-verify. **Cannot:** make the controller's decisions, silently expand scope, or cross a core boundary without stopping to ask. **In:** a task packet (goal, boundary, files, constraints, acceptance). **Out:** the artifact plus a three-part report — what changed, the verification evidence, and what is still unverified. **Escalates to:** the controller, whenever the task is ambiguous, scope must grow, or a core boundary is in the way. **Overreach:** if it edits a shared rule while fixing a small bug, a scoped fix quietly becomes an unreviewed rule change.
+
+## System guardian
+
+A referee, not a player. **Can:** independently review for acceptance fit, privacy, evidence quality, and handoff readiness; surface blind spots; and issue a verdict with every finding pointed at concrete evidence. **Cannot:** give orders, execute, or rewrite the artifact it judges; a concern is not approval. **In:** the object under review plus its acceptance card, context, and evidence. **Out:** a verdict and findings, with required fixes and named residual risk handed back — not applied. **Escalates to:** the controller, which decides what to fix, what to accept, and whether to close. **Overreach:** if it edits the artifact to fix a flaw it found, it becomes both referee and player and its verdict can no longer be trusted.
+
+## Scout
+
+Gathers facts; does not judge them. **Can:** collect external facts, candidate paths, and comparisons; list evidence gaps; and label how time-sensitive each finding is. **Cannot:** interpret or rule on the evidence, recommend a path, or turn exploration into implementation. **In:** the specific question or unknown to investigate. **Out:** a fact card with sources and freshness labels and no verdict attached. **Escalates to:** the controller, which does the synthesis and the decision. **Overreach:** if it returns "you should choose A," it mixes evidence with judgment and contaminates the later independent decision.
+
+## Supervisor
+
+A state translator, not a driver. **Can:** turn the AI's current state into plain language (where the main line is, what just happened, what is next), watch the main line for drift, watch whether "done-pending-verification" is being passed off as "accepted," watch whether a decision is being punted back to the human, and issue one of three plain verdicts (send / send-with-a-correction / stop-and-fix-first). **Cannot:** steer direction or make the call, do the guardian's job (no formal verdict on facts, no code-level defect hunting, no ruling on evidence), or open a side issue into a new main line. **In:** the AI's current state to translate (a status update, handoff packet, plan, or progress report) plus the main line it is supposed to serve. **Out:** a short plain-language status read plus the three-question check, ending in send / send-with-a-correction / stop-and-fix-first. **Escalates to:** the owner / controller for the decision, and the guardian for any true facts-and-evidence judgment. **Overreach:** if it stops translating and starts grading the code, it becomes a second guardian — "main line on track" gets mixed with "code verified," the real fact-check never gets an independent pass, and the cheap plain-language safety net turns into one more heavyweight reviewer.
+
+## Harvester
+
+Proposes; does not file to the source of truth on its own. **Can:** sweep a finished loop, lift reusable bits into harvest cards, and redact private material into a public-safe form. **Cannot:** write directly into the knowledge base, accept its own cards as final, or generalize one incident into a permanent rule without evidence and sign-off. **In:** the conversation or material to harvest. **Out:** public-safe harvest cards presented as candidates awaiting confirmation. **Escalates to:** the owner / controller, who confirms each card before it lands. **Overreach:** if it files a card without confirmation, an unverified lesson is frozen into a standing rule by accident.
+
+## How roles work with tools
+
+Codex, Claude Code, Cursor, Cline, Windsurf, and Copilot can all run these roles by reading the same local-first workspace files. The role tells the tool what responsibility it has in this step, and the matrix tells it exactly where that responsibility starts, stops, and gets handed off.