joycraft 1.1.1 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/README.md +57 -16
  2. package/dist/cli.js +50 -9
  3. package/dist/cli.js.map +1 -1
  4. package/dist/joycraft-release.json +1 -1
  5. package/package.json +3 -3
  6. package/payload/.agents/skills/joycraft-cleanup/SKILL.md +81 -34
  7. package/payload/.agents/skills/joycraft-context/SKILL.md +30 -4
  8. package/payload/.agents/skills/joycraft-decompose/SKILL.md +5 -1
  9. package/payload/.agents/skills/joycraft-entry/SKILL.md +35 -8
  10. package/payload/.agents/skills/joycraft-implement/SKILL.md +16 -0
  11. package/payload/.agents/skills/joycraft-session-end/SKILL.md +9 -4
  12. package/payload/.agents/skills/joycraft-testing/SKILL.md +7 -5
  13. package/payload/.agents/skills/joycraft-ui-slice/SKILL.md +4 -3
  14. package/payload/.agents/skills/joycraft-verify/SKILL.md +1 -1
  15. package/payload/.claude/agents/joycraft-reviewer.md +7 -2
  16. package/payload/.joycraft/assets/artifacts/kit.css +8 -0
  17. package/payload/.joycraft/assets/artifacts/kit.js +163 -21
  18. package/payload/.joycraft/assets/artifacts/transports.js +14 -3
  19. package/payload/.joycraft/contracts/types.d.ts +22 -0
  20. package/payload/.joycraft/references/archive.md +4 -2
  21. package/payload/.joycraft/references/artifacts.md +21 -2
  22. package/payload/.joycraft/references/cleanup.md +109 -3
  23. package/payload/.joycraft/references/completion.md +55 -2
  24. package/payload/.joycraft/references/context.md +64 -2
  25. package/payload/.joycraft/references/dispatch.md +12 -0
  26. package/payload/.joycraft/references/doc-cleanup-LICENSE.md +23 -0
  27. package/payload/.joycraft/references/knowledge.md +58 -0
  28. package/payload/.joycraft/references/setup.md +165 -151
  29. package/payload/.joycraft/references/testing.md +14 -7
  30. package/payload/.joycraft/references/update.md +13 -3
  31. package/payload/.joycraft/references/workflow.md +3 -2
  32. package/payload/.joycraft/runtime/archive.mjs +19 -4
  33. package/payload/.joycraft/runtime/artifacts/decisions.mjs +16 -5
  34. package/payload/.joycraft/runtime/artifacts/server.mjs +14 -1
  35. package/payload/.joycraft/runtime/cleanup.mjs +95 -8
  36. package/payload/.joycraft/runtime/completion.mjs +210 -10
  37. package/payload/.joycraft/runtime/config.mjs +5 -3
  38. package/payload/.joycraft/runtime/dispatch-preflight.mjs +16 -3
  39. package/payload/.joycraft/runtime/evidence.mjs +4 -0
  40. package/payload/.joycraft/runtime/identity.mjs +11 -0
  41. package/payload/.joycraft/runtime/review-tools.json +110 -30
  42. package/payload/.joycraft/runtime/review-tools.mjs +702 -131
  43. package/payload/.joycraft/runtime/status.mjs +1 -1
  44. package/payload/.joycraft/runtime/update-check.mjs +38 -8
  45. package/payload/.joycraft/runtime/wiring.mjs +156 -0
  46. package/payload/.joycraft/runtime/worktrees.mjs +1 -1
  47. package/payload/.joycraft/templates/joycraft.yaml +2 -0
  48. package/payload/.joycraft/templates/project-context.md +6 -1
  49. package/payload/PIN +45 -42
@@ -1,4 +1,11 @@
1
- # Project context ranking
1
+ # Project context
2
+
3
+ ## Contents
4
+
5
+ - [Finding context](#finding-context)
6
+ - [Changing context](#changing-context)
7
+
8
+ ## Finding context
2
9
 
3
10
  From the consumer Git project root:
4
11
 
@@ -81,5 +88,60 @@ advise reading order and never approve intent, authorize work or certify evidenc
81
88
 
82
89
  Treat only the context homes as current authority. `docs/features/` is working
83
90
  material that can be stale until its feature is archived, and `docs/archive/` is
84
- history; see the knowledge-home table in `setup.md`. Joycraft ships no wiki. Skills
91
+ history; see [knowledge guidance](knowledge.md) for which home holds what. Joycraft ships no wiki. Skills
85
92
  do not need to be named by the user: pick the step from the request.
93
+
94
+ ## Changing context
95
+
96
+ The same skill writes project knowledge when the user asks: "add this to the
97
+ project context", "remember that ...", "forget that rule", or a meeting note,
98
+ screenshot or pasted text to capture. `knowledge.md` owns the rule (one home per
99
+ fact, current state only, reasons in the decision log, history in the archive);
100
+ these steps apply it to a request.
101
+
102
+ **Read the map and homes.** Start from the context map in `AGENTS.md` (or the
103
+ project's own map). Search the live homes, not `docs/features/` or
104
+ `docs/archive/`, for the subject of each fact: a different wording of the same
105
+ rule counts as the same fact.
106
+
107
+ **Turn input into facts.** A meeting note, screenshot or pasted thread usually
108
+ holds several facts and some noise. Keep each statement that was settled or
109
+ observed: a decision and its reason, a trap and how to avoid it, a reference, a
110
+ production fact. Leave out action items, open questions, ideas nobody decided
111
+ on, attendance and opinions; name them in the proposal as left out, so the user
112
+ can correct the cut. For a screenshot, read the facts from what it shows and
113
+ say which ones you could not read. Do not copy the raw note into the project,
114
+ and do not keep a link to it as a source: the homes state the facts themselves.
115
+
116
+ **Add.** Route each fact by the table in `knowledge.md` to the home the map
117
+ already names for that kind. When the map has no home for it, create a focused
118
+ page under the context folder with the fact and add a map row whose "read when"
119
+ names the work that needs it, not the page's title. Write a decision's current
120
+ choice in the home that owns its area and its reason and rejected options as a
121
+ decision-log entry. A widened home keeps a "read when" that covers its new
122
+ content.
123
+
124
+ **Change.** Rewrite the existing statement in place. Add a decision-log entry
125
+ that names the old choice, the new one and why. Leave no dated addendum,
126
+ "previously" note or struck-through text in the live home.
127
+
128
+ **Remove.** Delete the statement from every live home that holds it, including
129
+ copies in `AGENTS.md`. Add a decision-log entry headed with what was removed,
130
+ with the user's reason; when the user gives none, ask, and in a pre-approved
131
+ non-interactive run write that it was removed at the user's request. An older
132
+ decision-log entry that chose the rule stays as history; the new entry records
133
+ that it no longer applies. When the page that held it has no facts left, delete
134
+ the page, its map row and every link or backticked mention of it. Do not leave
135
+ an empty page, a row to a missing file or a "removed" note in a live home.
136
+
137
+ **Approve, then write.** Before writing, show each affected file and the change
138
+ as a unified diff (or the new file in full), the home chosen for each fact, and
139
+ anything left out. Write only after the user says yes, and only what they
140
+ approved. A prompt that already approves the change, as in a scripted run, is
141
+ that yes; still show what you wrote afterwards.
142
+
143
+ **Check the map.** Run `node .joycraft/runtime/cleanup.mjs`. The change must not
144
+ add a `missing-path`, `unmapped`, `orphan`, `broken-link` or `working-link`
145
+ finding; fix any it did. Report findings that were already there without fixing
146
+ them unless the user asks. Every page you created or edited must be reachable
147
+ from the map.
@@ -10,6 +10,9 @@ For a mutable worker or stateful runtime check, first apply the conditional
10
10
  worktree or a resource lease. A `read-only` workspace keeps declared source
11
11
  inputs frozen; it may still write declared review reports and receipts outside
12
12
  those inputs. Cache-mutating runtime work needs separate mutable state.
13
+ Reviewer preflight refuses a queue whose feature `waiver.json` covers
14
+ `no-review` ([completion guidance](completion.md#feature-waiver)); complete
15
+ those specs with `accept-waiver` instead.
13
16
 
14
17
  ## Contents
15
18
 
@@ -93,6 +96,11 @@ more, alone, with a fresh packet path. If it fails again, stop that spec's
93
96
  review and tell the user its printed reason; never continue as if the review
94
97
  started. Do not retry a `Task startup stopped:` refusal unchanged; fix its cause.
95
98
 
99
+ A worker that holds a spec for a tool break reports the spec, the tool, the
100
+ cause and the repair it tried. The coordinator tells the user at the first hold,
101
+ in the conversation, while other workers keep running; it does not wait for the
102
+ session end. The session-end summary lists every held spec again.
103
+
96
104
  The return is `ready: true` for an available valid startup path, including a
97
105
  hooks-disabled/manual path. It is not a cryptographic attestation. Missing human
98
106
  prompt history for an enforced startup is explicit
@@ -158,6 +166,10 @@ decisions. Without a selector, the packet conservatively carries every current
158
166
  answered decision from that brief. The packet retains its whole-brief reference
159
167
  so workers can read each decision in context. Its inputs include any current
160
168
  coupled counterpart required to review the requested behavior.
169
+ When `AGENTS.md` has a `## Review loop` section or this machine has
170
+ `.joycraft/local/review-loop.json`, the packet carries `reviewLoop`:
171
+ `{ path, section, local? }`, the shared section plus, when present,
172
+ `local: { path, record }` with this machine's host tools.
161
173
 
162
174
  ## Bind the hook source view
163
175
 
@@ -0,0 +1,23 @@
1
+ License for the doc-cleanup method adapted in joycraft-cleanup, from https://github.com/aka-luan/doc-cleanup (commit 69dcb95):
2
+
3
+ MIT License
4
+
5
+ Copyright (c) 2026 aka-luan
6
+
7
+ Permission is hereby granted, free of charge, to any person obtaining a copy
8
+ of this software and associated documentation files (the "Software"), to deal
9
+ in the Software without restriction, including without limitation the rights
10
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
11
+ copies of the Software, and to permit persons to whom the Software is
12
+ furnished to do so, subject to the following conditions:
13
+
14
+ The above copyright notice and this permission notice shall be included in all
15
+ copies or substantial portions of the Software.
16
+
17
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
22
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
23
+ SOFTWARE.
@@ -0,0 +1,58 @@
1
+ # Project knowledge stays current
2
+
3
+ The context map in `AGENTS.md` (or the project's own map) is the index of project
4
+ memory. Each row points to one home for one kind of knowledge and says when to
5
+ read it. An agent that starts fresh, after a compaction or in a new session,
6
+ reads the homes as the current state of the project. It must never have to replay
7
+ a chain of past decisions to learn how things are today.
8
+
9
+ ## The rule
10
+
11
+ - **One home per fact.** Other pages link to it; they do not copy it.
12
+ - **Homes state what is true now.** When a fact changes, rewrite the statement in
13
+ place. Do not add a dated addendum, a "superseded by" or "previously" note,
14
+ struck-through text, or a footnote that corrects a stale table.
15
+ - **Why goes to the decision log.** The reason and the rejected options go in an
16
+ entry in the decision log (default `docs/context/decision-log.md`). A changed
17
+ decision gets a new entry that names the choice it replaces. The live home
18
+ carries only the current statement.
19
+ - **History stays out of live homes.** The old value of a changed fact lives in
20
+ its decision-log entry and in Git. Finished features go to the archive at
21
+ session end (`archive.md`); they stay there for regression checks and are never
22
+ read as current truth.
23
+ - **Check before you restore.** Do not copy a statement from the archive or from
24
+ an old decision-log entry back into a live home until you have checked it
25
+ against the code.
26
+ - Record what the work established or observed. Keep proposals and guesses out.
27
+
28
+ ## Routing a fact at session end
29
+
30
+ A reusable fact is one a later session needs and cannot cheaply get from the
31
+ code. Use the home the map already names for that kind. Use the default only when
32
+ the map has no home for it.
33
+
34
+ | Fact | Home |
35
+ |---|---|
36
+ | What the project is (purpose, users, owners, constraints), and the areas setup has not mapped yet | `docs/context/project.md` (from `.joycraft/templates/project-context.md`) |
37
+ | Navigation across code boundaries (where a flow lives) | A focused reference page linked by the map, e.g. `docs/context/architecture.md` |
38
+ | Decision | Current choice in the home that owns that area; reason and rejected options in the decision log |
39
+ | Trap (something that misleads or breaks, and how to avoid it) | The project's troubleshooting or gotchas page, default `docs/context/traps.md` |
40
+ | Reference (where something lives, how to run or look it up) | A focused reference page linked by the map |
41
+ | Production fact (deploy, environments, data, external services) | The production page, default `docs/context/production.md` |
42
+ | Feature intent and product choices for live work | The feature brief; do not copy them into a context home |
43
+
44
+ For each fact:
45
+
46
+ 1. Find its home through the map. If the home already states it, rewrite that
47
+ statement in place.
48
+ 2. If no home holds that kind of fact, create the page with the fact and add a
49
+ map row with a "read when". Do not create empty pages.
50
+ 3. If a change widens or narrows what a home covers, edit its row so the "read
51
+ when" stays true.
52
+
53
+ Then check that every page you created or edited is reachable from the map, that
54
+ no link points into `docs/features/` or `docs/archive/`, and that no live home
55
+ holds a dated addendum or "superseded" note (`node .joycraft/runtime/cleanup.mjs`
56
+ reports unmapped pages and broken or working-material links).
57
+
58
+ A session with nothing reusable changes no context file.
@@ -1,21 +1,17 @@
1
1
  # First-use project setup
2
2
 
3
- Use this on first entry, an explicit setup/init request, or a missing context
4
- home. It is an agent-guided part of `joycraft-entry`, not an installer side
5
- effect or a separate interview; the one exception is the opt-in
6
- [kickoff for a new project](#kickoff-for-a-new-project). Work inside the current project. Read-only
7
- requests do not authorize setup writes.
8
-
9
- For a reviewed clone, `node scripts/setup.mjs --target <project>` previews the
10
- smallest missing knowledge homes. Add `--write` only after reviewing the preview.
11
- It reads only plain target-local repository facts; it never reads `.env.local`,
12
- Keychain, sibling projects, or private directories. Its `ready` and `partial`
13
- status describes context discovery, never hook trust or a successful command.
3
+ Run this after every install from the prompt, when the user asks ("set up
4
+ Joycraft", "check the context map"), and whenever
5
+ `node .joycraft/runtime/wiring.mjs --root .` exits 2. The CLI knows nothing
6
+ about the project, so it writes nothing to `AGENTS.md` or `CLAUDE.md`; you build
7
+ the context map from the repository and a short interview with the user. Many
8
+ installs land in existing, sometimes large, projects, so the interview is part
9
+ of every setup, not only a new project's. Work inside the current project. A
10
+ read-only request gets the findings reported, not written.
14
11
 
15
12
  ## Contents
16
13
 
17
- - [Discover before writing](#discover-before-writing)
18
- - [Small shared entry point](#small-shared-entry-point)
14
+ - [Set up the context map](#set-up-the-context-map)
19
15
  - [Kickoff for a new project](#kickoff-for-a-new-project)
20
16
  - [Review loop tools](#review-loop-tools)
21
17
  - [Project-owned worktrees](#project-owned-worktrees)
@@ -23,87 +19,99 @@ status describes context discovery, never hook trust or a successful command.
23
19
  - [Finish setup and continue](#finish-setup-and-continue)
24
20
  - [Upgrade and agent onboarding](#upgrade-and-agent-onboarding)
25
21
 
26
- ## Discover before writing
27
-
28
- Read applicable instructions, root `AGENTS.md` and `CLAUDE.md` if present, README,
29
- and the relevant existing context links. Inspect manifests, lockfiles, task
30
- scripts and CI only as needed to establish the stack and actual commands. Follow
31
- the project's documentation conventions instead of migrating them into ours.
32
- Do not scan neighboring projects or credential files. Do not run installs,
33
- deployments, destructive commands, or application setup just to populate a table.
34
-
35
- Use the current conversation for intended users, purpose, stakeholders and
36
- constraints. Separate user-stated intent from repository observations and your
37
- assumptions. A declared command is not a verified successful command: cite its
38
- manifest/script source and mark it unrun until actually executed. On a bare
39
- project, say the stack and commands are not established; do not choose them for
40
- the sake of setup. Offer the kickoff below instead.
41
-
42
- When the current authorized work exposes an unclear state, data, or
43
- responsibility boundary, inspect the relevant owner and its actual counterparts
44
- before recording guidance. Preserve source-backed navigation in the existing
45
- context map or reference home; keep product behavior in the current brief. Read
46
- `architecture.md` for this focused, conditional discovery. Do not create an
47
- architecture phase, architecture-complete marker, or empty map during setup.
48
-
49
- ## Small shared entry point
50
-
51
- If `AGENTS.md` is missing, create a concise project-specific file with:
52
-
53
- - Project purpose supported by the request or repository; if unknown, say so.
54
- - Existing commands, their source and execution status, when available.
55
- - Only established project constraints, preserving their scope.
56
- - A context map with project-relative links and a short “read when” for each.
57
- - This line: “First action in each session: run
58
- `node .joycraft/runtime/update-check.mjs check`. If it prints JSON, follow
59
- `.joycraft/references/update.md`.”
60
- - This line: “Show every document a person must read, review or answer (a brief,
61
- plan, spec set, review or set of questions) as a rendered page, never only as
62
- Markdown in chat: use the decision artifact
63
- (`node .joycraft/runtime/artifacts/cli.mjs`, see `.joycraft/references/artifacts.md`)
64
- for a brief or questions, or an HTML page for any other document. Open it for
65
- the person and say where it is.”
66
- - A context-map row for `.joycraft/references/artifacts.md`, read when “showing a
67
- document or questions to a person”.
68
-
69
- Do not copy prototype-maintainer rules or fill it with generic coding advice.
70
- Link detail rather than duplicating it. Do not encode a tentative product idea
71
- as a permanent boundary. Keep current feature intent in its brief.
72
-
73
- If `AGENTS.md` already exists, preserve its content and add only missing facts,
74
- useful context pointers, the update-check line, the rendered-documents line and its
75
- context-map row above with a targeted edit. Reuse an existing context map
76
- rather than adding another. Read linked content before deciding it is missing.
77
- When its map names a project-context home, use that exact project-relative home;
78
- use `docs/context/project.md` only when no context home exists. Do not link a
79
- context document that setup did not create or find. This keeps a bare project
80
- free of dangling links.
81
- Do not reformat, delete, or replace user instructions. Surface consequential
82
- contradictions rather than silently resolving them. Respect symlinks and managed
83
- files; do not replace them or write outside the project through them.
84
-
85
- For a missing `CLAUDE.md`, create a thin pointer after `AGENTS.md` exists:
86
-
87
- ```md
88
- @AGENTS.md
89
- ```
90
-
91
- For an existing `CLAUDE.md`, preserve all guidance. Add the import only if there
92
- is no equivalent link and it would not create a reference cycle. If CLAUDE.md is
93
- already the shared authority, keep it there and let the new AGENTS.md point to
94
- it; do not create reciprocal imports or duplicate its rules. This shared context
95
- pointer does not itself install skills or hooks; the exporter must use
96
- `--harness claude` to place those in Claude discovery paths.
97
-
98
- Before assigning workers, read an existing `.joycraft/preferences.json`. Reuse
99
- explicit model, effort, role, concurrency, and verification choices. Then inspect
100
- the active host for the actual planner, implementer, reviewer, testing, UI, and
101
- fixture capabilities. Generated defaults and an `unknown` fixture status do not
102
- prove capability. Until actual isolation is established, use at most four workers
103
- and one UI worker. Relevant acceptance requires both an inspected rendered UI
104
- and independent review; if one is unavailable, hold only the claim it would
105
- support. Ask one short combined question only when a consequential choice remains
106
- after that inspection.
22
+ ## Set up the context map
23
+
24
+ The context map in `AGENTS.md` is the project's memory index. Each row points to
25
+ one home for one kind of knowledge and says when to read it, so an agent loads
26
+ only what its work needs; the map then grows with every decision, trap and
27
+ feature ([knowledge.md](knowledge.md)). A project without a real map gets
28
+ nothing from Joycraft, so build it from the project, never from a template.
29
+
30
+ **Nothing new, nothing done.** When `wiring.mjs` exits 0, every doc worth
31
+ reading already has a row, and nothing the user told you or the audit found is
32
+ unrecorded, say in one line that Joycraft is already set up. Write nothing,
33
+ render nothing, ask nothing: a repeated setup must leave the project unchanged.
34
+
35
+ 1. **Read and audit.** Read `AGENTS.md`, `CLAUDE.md`, the README and every doc
36
+ they point to, then the other Markdown docs (skip dependencies, generated
37
+ files, `.joycraft/` and installed skills). Run `joycraft-cleanup` steps 1–2
38
+ (inventory and diagnose) on what you read: it gives each doc a
39
+ [role](cleanup.md#doc-roles) and hands its findings back to you, with no
40
+ report page and no stop of its own. Check claims in entry and required docs
41
+ against the code; in reference docs, check only the claims the interview or
42
+ an audit finding touches. Inspect manifests, scripts and CI only to
43
+ establish the stack and real commands; a declared command is unrun until
44
+ executed. In a large repo, read the entry docs and their pointers first,
45
+ then one area at a time; propose each area you did not read as an item of
46
+ a `## Not yet mapped` list in `docs/context/project.md` (current areas
47
+ only, no history), so a later session maps it when work reaches it. Do
48
+ not scan neighboring projects or credential files, and do not run
49
+ installs, deployments or destructive commands.
50
+ 2. **Interview.** Ask only what the repository cannot tell you: purpose, users,
51
+ who owns what, constraints, decisions already made and why, which docs are
52
+ trusted, and each audit finding that needs a human. Ask in short rounds of
53
+ at most three questions, each one that changes what you will write. Write
54
+ each choice with options as a decision in a setup brief at
55
+ `.joycraft/local/setup/brief.md` (format of `.joycraft/templates/brief.md`,
56
+ `feature: setup`; give `.joycraft/local/` a `.gitignore` of `*` when it has
57
+ none, so nothing there becomes a project change) and serve the decision
58
+ artifact on it ([artifacts.md](artifacts.md)); plain chat is only for one
59
+ quick yes/no or an open question with no options. The brief is scratch:
60
+ each answer then goes to its home in step 3. Stop when the user says enough. Never ask again
61
+ what the user answered or a home already states. Keep the user's words apart
62
+ from your observations and assumptions. On a bare project, offer the
63
+ [kickoff](#kickoff-for-a-new-project) instead.
64
+ 3. **Propose.** Draft every change:
65
+ - **Joycraft lines** in `AGENTS.md`, each only when missing:
66
+ “First action in each session: run
67
+ `node .joycraft/runtime/update-check.mjs check`. If it prints JSON, follow
68
+ `.joycraft/references/update.md`.” and “Show every document a person must
69
+ read, review or answer (a brief, plan, spec set, review or set of
70
+ questions) as a rendered page, never only as Markdown in chat: use the
71
+ decision artifact (`node .joycraft/runtime/artifacts/cli.mjs`, see
72
+ `.joycraft/references/artifacts.md`) for a brief or questions, or an HTML
73
+ page for any other document. Show it where the person works (see
74
+ `.joycraft/references/artifacts.md#showing-a-page`) and say where it is.”
75
+ - **The map**: one `## Context Map` table (`| Document | Read when |`). One
76
+ row per real home: each required or reference doc, and each home you
77
+ create. A read-when names the work that needs the doc ("Changing how counts
78
+ are stored"), not its topic. Add a row for
79
+ `.joycraft/references/artifacts.md`, read when "showing a document or
80
+ questions to a person". Historical docs get no row. In an existing map,
81
+ append rows below the user's rows; never edit, reorder or reformat theirs.
82
+ Every row targets a file that exists after the write.
83
+ - **Homes**, only with content, routed by [knowledge.md](knowledge.md).
84
+ - **`CLAUDE.md`**, only when `.joycraft/installation.json` lists the
85
+ `claude` host: missing → create it as `@AGENTS.md` followed by an empty
86
+ `## Claude Code` section; present without an `@AGENTS.md` line → add
87
+ `@AGENTS.md` as line 1; present with it → leave it alone. When `AGENTS.md`
88
+ already imports or defers to `CLAUDE.md`, add no reciprocal import.
89
+ - **Audit fixes** for the findings the user agreed to in the interview, made
90
+ as joycraft-cleanup step 4 says.
91
+
92
+ Add lines, rows and pages. Do not reword, reformat, reorder or delete user
93
+ content: every existing line of `AGENTS.md` and `CLAUDE.md` survives. With
94
+ no `AGENTS.md`, create one with the purpose (or "unknown"), established
95
+ constraints, commands with their source, the Joycraft lines and the map. Keep
96
+ generic coding advice and tentative product ideas out; feature intent stays
97
+ in its brief. Respect symlinks and managed files.
98
+ 4. **Show, then write.** Render the diff of every file you would change or
99
+ create, audit fixes included, as one HTML page under
100
+ `.joycraft/local/setup/`. Show it as [showing a page](artifacts.md#showing-a-page)
101
+ says, give its path, and write only on the
102
+ user's yes; this page is setup's only approval stop. A request that
103
+ already approves the files you propose counts as the yes.
104
+ 5. **Check.** `wiring.mjs` exits 0. `node .joycraft/runtime/cleanup.mjs`
105
+ reports no `missing-path`, `unmapped`, `orphan` or `broken-link` for the
106
+ files you touched. Every original line of `AGENTS.md` and `CLAUDE.md` is
107
+ still there. Fix what fails, then tell the user in a few lines which docs the
108
+ map now reaches, which homes you created and what you have not read or do
109
+ not know yet. Continue the original request.
110
+
111
+ When the work exposes an unclear state, data, or responsibility boundary,
112
+ inspect the owner and its actual counterparts before recording guidance; read
113
+ `architecture.md` for that focused check. Do not create an architecture phase,
114
+ architecture-complete marker, or empty map during setup.
107
115
 
108
116
  ## Kickoff for a new project
109
117
 
@@ -158,26 +166,54 @@ Pass `--host-tools browser`, `simulator` or `computer-use` only for tools the
158
166
  active host actually reports; they can stand in for a missing install. The plan
159
167
  detects each package from its manifests, probes versions read-only, and prints
160
168
  one table and at most one question. It never installs. When it prints
161
- `Review loop unchanged.`, ask nothing.
162
-
163
- Show the table and ask its one question. Only after the user's yes in this
164
- conversation, run `review-tools.mjs install --root . --yes` (add
165
- `--tools <ids>` for a per-tool choice); it adds project-local tools with the
166
- project's own package manager and lockfile. Never run a system install, `sudo`,
167
- a license acceptance or a sign-in: give the user the printed steps. Then record
168
- the choice, with `--skip <ids>` for declined tools:
169
+ `Review loop unchanged.`, ask nothing. Packages come from declared workspaces;
170
+ with none and no root manifest, from the manifests below the root that git does
171
+ not ignore. When it prints `No packages found`, ask the user which folders hold
172
+ the apps and pass them as `--packages <dir,dir>` to `plan`, `install` and
173
+ `record`.
174
+
175
+ Show the table: what the plan found per package. Ask the user to confirm it or
176
+ name a tool the plan missed, together with its one question. For a gap, say
177
+ plainly that automated review of that package needs a tool that can show the
178
+ work. Recommend one from the hint list (`review-tools.json`), with its
179
+ trade-offs: size, what it can show, cost and licence. Say you are happy to
180
+ research other options. Explain what the install runs and where, then wait for
181
+ the user's yes in this conversation before you run
182
+ `review-tools.mjs install --root . --yes` (add `--tools <ids>` for a per-tool
183
+ choice or a hint the user picked). It adds project-local tools with the
184
+ project's own package manager and lockfile. It also runs a user-scope CLI
185
+ install (`npm install -g`, `brew install`) when the hint marks no `sudo`,
186
+ licence or sign-in. Never run `sudo`, a licence acceptance or a sign-in: give
187
+ the user the printed `steps`. Then record the choice:
169
188
 
170
189
  ```sh
171
- node .joycraft/runtime/review-tools.mjs record --root . --skip <ids>
190
+ node .joycraft/runtime/review-tools.mjs record --root . [--choose <package>=<tool>] [--command <package>=<command>] [--skip <tool>|<package>:<tool>|<package>] [--host <name> --host-tools <observed host tools>]
172
191
  ```
173
192
 
174
- This writes or replaces only the `## Review loop` section of `AGENTS.md`: each
175
- tool, the command that starts the app and the command that takes the evidence.
176
- Worker packets carry that section. For a skipped UI tool, say in one line that
177
- its UI claims stay `UNVERIFIED`. With no network, the probes still run; offer
178
- the install later. For a CI-only project, record the CI job as the evidence
193
+ `--choose` records the tool the user picked for a package (a hint id, or a
194
+ found script with its `--command`); `'apps/*'=<tool>` records one shared harness
195
+ for those packages. `--skip <tool>` skips that missing tool in every package;
196
+ `--skip apps/lab:<tool>` or `--skip apps/lab` skips only that package. Repeat
197
+ `--command` per value. This writes or replaces only the `## Review loop` section
198
+ of `AGENTS.md`: one row per package with its tool, what it can show, the command
199
+ that starts the app and the command that takes the evidence. Recording again
200
+ keeps earlier choices and skips for packages the call does not name. Host tools
201
+ go to the git-ignored `.joycraft/local/review-loop.json`, never `AGENTS.md`.
202
+ Worker packets carry both. A skipped package's row says it is not reviewed
203
+ (user skipped). With no network, the probes still run; offer the install later. For a CI-only project, record the CI job as the evidence
179
204
  source when the user picks it.
180
205
 
206
+ **Change a tool.** Talk about the review loop only here: at install, at
207
+ setup and upgrade when the plan reports a change, and when the user asks to
208
+ try, switch, add or remove a tool ("try Maestro for the iOS app"). For a
209
+ request, confirm or research the tool, install it as above, and re-record only
210
+ that package with `--choose <package>=<tool>` (or `--skip` to remove one);
211
+ other rows stay. When the plan's `Changed since the recorded Review loop` names
212
+ a newly detected tool, offer to switch that package to it. When it reports
213
+ `recorded with v1; re-record to keep it`, confirm the table with the user and run
214
+ record again, repeating any `--choose` or `--skip` the table shows; a v1 record
215
+ does not carry them over. An unchanged project asks nothing.
216
+
181
217
  `review-tools.json` also lists `optIn` tools that detection never plans. Offer
182
218
  one only when it fits the project. Example: Doc Detective, for docs that are
183
219
  step-by-step procedures. Say what it does not cover and that it is AGPL-3.0 with a
@@ -230,23 +266,9 @@ explicit manual Git-worktree workflow.
230
266
 
231
267
  ## Knowledge grows with the work
232
268
 
233
- Reuse existing documents for project facts. If none exists and there are durable
234
- facts worth retaining, create `docs/context/project.md` with the known purpose,
235
- users/stakeholders and constraints, their source, and any consequential unknowns.
236
- Create its parent directory and link it from the context map. Omit empty sections
237
- and private contact details that are unnecessary for the work. If nothing is
238
- known yet, create only the instruction files; gather the first useful fact before
239
- creating a context document. Do not manufacture a directory tree of empty files.
240
-
241
- Create additional homes only when they have content:
242
-
243
- | Content | Default home when no existing convention applies |
244
- |---|---|
245
- | Durable project knowledge | `docs/context/project.md` or a focused reference linked by the map |
246
- | Source-backed cross-boundary navigation | The existing context map or a focused reference linked by it |
247
- | Reusable decision rationale | `docs/context/decision-log.md`, linking to the owning decision |
248
- | Current feature or mixed change | `docs/features/<slug>/brief.md` |
249
- | Authorized implementation queue | `docs/features/<slug>/specs/` |
269
+ Which home holds which kind of fact, and when to create one, is in
270
+ [knowledge guidance](knowledge.md). A current feature lives in
271
+ `docs/features/<slug>/brief.md` and its queue in `docs/features/<slug>/specs/`.
250
272
 
251
273
  A project can move these folders, add an after-archive hook and map code to
252
274
  context pages in an optional root `joycraft.yaml`. It is project-owned: create it
@@ -263,16 +285,16 @@ and links it from the context map.
263
285
 
264
286
  The brief retains decision authority under `workflow.md`; the context document
265
287
  and decision log must not become competing answer stores. Later accepted facts
266
- update their existing home. Repeating entry with no new knowledge should make
288
+ update their existing home; [knowledge.md](knowledge.md) owns how each fact is
289
+ routed, changed in place and kept current. Repeating entry with no new knowledge should make
267
290
  no setup edits, create no duplicate links, and ask no repeated questions. There
268
291
  is no setup-complete sentinel: useful source content, not a flag, determines
269
292
  whether context is available.
270
293
 
271
- Ask only for missing human knowledge that materially changes the next action.
272
- Prefer one short contextual question and continue independent work while it is
273
- pending. An explicit setup-only request with no product context may end with that
274
- question or the kickoff offer; do not generate a questionnaire or start building
275
- an imagined app.
294
+ Outside setup's interview, ask only for missing human knowledge that materially
295
+ changes the next action. Prefer one short contextual question and continue
296
+ independent work while it is pending. Do not generate a questionnaire or start
297
+ building an imagined app.
276
298
 
277
299
  Use the project’s existing interaction home for a choice. A question with
278
300
  options goes in the decision artifact; only one quick yes/no or an open question
@@ -281,28 +303,20 @@ owning brief and do not ask it again.
281
303
 
282
304
  ## Finish setup and continue
283
305
 
284
- Check that newly added links resolve, command claims match their cited source,
285
- and existing guidance survived the diff. Briefly tell the user which knowledge
286
- homes were created or extended and any important unknown; then continue the
287
- original request. Setup does not approve hooks, change credentials, install
306
+ Step 5 of [Set up the context map](#set-up-the-context-map) is the finish
307
+ check; also check that command claims match their cited source. Setup does not approve hooks, change credentials, install
288
308
  dependencies, or replace the user's workflow. Read `hooks-install.md` only when
289
309
  hook activation is part of the requested setup.
290
310
 
291
311
  ## Upgrade and agent onboarding
292
312
 
293
- Use `node scripts/export.mjs --target <project> --check --upgrade` to preview an
294
- upgrade. It names only recognized old Joycraft files that would be replaced.
295
- Applying without `--check` copies those replaced bytes to `.joycraft-backups/`
296
- first and writes `.joycraft/installation.json`, whose hashes attest to
297
- the actual installed skill, reference, and runtime bytes. A changed file absent
298
- from the prior installation manifest remains a conflict; there is no blanket
299
- force flag. The manifest is dispatch input, not proof that hooks ran or that a
300
- review was independent.
301
-
302
- For a new worker, copy the onboarding prompt from the setup preview. It directs
303
- the worker to read existing project preferences before work, reuse explicit
304
- model/effort/role/concurrency/verification choices, and inspect the host's
305
- currently available planner, implementer, reviewer, testing, UI, and fixture
306
- capabilities rather than claiming a hardcoded model is available. State
307
- unavailable roles and native-hook checks plainly. Do not alter accepted queues,
308
- decision state, user guidance, or credentials during setup or upgrade.
313
+ Updates go through the Joycraft CLI; follow [update guidance](update.md). The
314
+ installation manifest `.joycraft/installation.json` records the installed bytes;
315
+ it is dispatch input, not proof that hooks ran or that a review was independent.
316
+
317
+ A new worker reads `.joycraft/preferences.json` before work, reuses explicit
318
+ model, effort, role, concurrency and verification choices, and inspects the
319
+ host's available planner, implementer, reviewer, testing, UI and fixture
320
+ capabilities instead of assuming a model. It states unavailable roles plainly.
321
+ Setup and upgrade never change accepted queues, decision state, user guidance or
322
+ credentials.