@granular-software/fractory 0.0.0-stage → 0.1.24

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 (273) hide show
  1. package/LICENSE +4 -0
  2. package/README.md +28 -2
  3. package/dist/activity-volume.d.ts +18 -0
  4. package/dist/activity-volume.js +94 -0
  5. package/dist/annotations.d.ts +118 -0
  6. package/dist/annotations.js +304 -0
  7. package/dist/benchmark-cli.d.ts +1 -0
  8. package/dist/benchmark-cli.js +95 -0
  9. package/dist/benchmark-worker.d.ts +2 -0
  10. package/dist/benchmark-worker.js +22 -0
  11. package/dist/benchmarks.d.ts +19 -0
  12. package/dist/benchmarks.js +414 -0
  13. package/dist/bin.d.ts +2 -0
  14. package/dist/bin.js +63 -0
  15. package/dist/block-cli.d.ts +1 -0
  16. package/dist/block-cli.js +88 -0
  17. package/dist/block-documents.d.ts +35 -0
  18. package/dist/block-documents.js +84 -0
  19. package/dist/change-impact.d.ts +55 -0
  20. package/dist/change-impact.js +223 -0
  21. package/dist/check-source.d.ts +2 -0
  22. package/dist/check-source.js +66 -0
  23. package/dist/checks-model.d.ts +64 -0
  24. package/dist/checks-model.js +36 -0
  25. package/dist/cli.d.ts +2 -0
  26. package/dist/cli.js +359 -0
  27. package/dist/code-model.d.ts +38 -0
  28. package/dist/code-model.js +94 -0
  29. package/dist/code-store.d.ts +9 -0
  30. package/dist/code-store.js +79 -0
  31. package/dist/compare-artifact.d.ts +6 -0
  32. package/dist/compare-artifact.js +277 -0
  33. package/dist/compare.d.ts +81 -0
  34. package/dist/compare.js +291 -0
  35. package/dist/compiler.d.ts +10 -0
  36. package/dist/compiler.js +1083 -0
  37. package/dist/compose.d.ts +9 -0
  38. package/dist/compose.js +72 -0
  39. package/dist/core.d.ts +86 -0
  40. package/dist/core.js +206 -0
  41. package/dist/coverage-cli.d.ts +1 -0
  42. package/dist/coverage-cli.js +42 -0
  43. package/dist/declaration-sources.d.ts +3 -0
  44. package/dist/declaration-sources.js +51 -0
  45. package/dist/declared-graph.d.ts +3 -0
  46. package/dist/declared-graph.js +66 -0
  47. package/dist/display-name.d.ts +2 -0
  48. package/dist/display-name.js +8 -0
  49. package/dist/error-heat.d.ts +58 -0
  50. package/dist/error-heat.js +96 -0
  51. package/dist/evidence.d.ts +3 -0
  52. package/dist/evidence.js +68 -0
  53. package/dist/factory-graph.d.ts +4 -0
  54. package/dist/factory-graph.js +318 -0
  55. package/dist/factory-model.d.ts +97 -0
  56. package/dist/factory-model.js +1 -0
  57. package/dist/git-code.d.ts +47 -0
  58. package/dist/git-code.js +352 -0
  59. package/dist/git-refs.d.ts +4 -0
  60. package/dist/git-refs.js +37 -0
  61. package/dist/history-activity.d.ts +4 -0
  62. package/dist/history-activity.js +129 -0
  63. package/dist/history-churn.d.ts +36 -0
  64. package/dist/history-churn.js +302 -0
  65. package/dist/history-git.d.ts +21 -0
  66. package/dist/history-git.js +125 -0
  67. package/dist/history-ledger.d.ts +43 -0
  68. package/dist/history-ledger.js +450 -0
  69. package/dist/history-ownership.d.ts +10 -0
  70. package/dist/history-ownership.js +75 -0
  71. package/dist/history-source.d.ts +13 -0
  72. package/dist/history-source.js +100 -0
  73. package/dist/integrations-cli.d.ts +2 -0
  74. package/dist/integrations-cli.js +159 -0
  75. package/dist/issue-cache.d.ts +9 -0
  76. package/dist/issue-cache.js +68 -0
  77. package/dist/issue-cli.d.ts +1 -0
  78. package/dist/issue-cli.js +89 -0
  79. package/dist/issue-links.d.ts +15 -0
  80. package/dist/issue-links.js +125 -0
  81. package/dist/linear-issues.d.ts +19 -0
  82. package/dist/linear-issues.js +124 -0
  83. package/dist/local-runtime.d.ts +8 -0
  84. package/dist/local-runtime.js +59 -0
  85. package/dist/map-activity.d.ts +73 -0
  86. package/dist/map-activity.js +234 -0
  87. package/dist/map-model.d.ts +5 -0
  88. package/dist/map-model.js +166 -0
  89. package/dist/map-quality.d.ts +14 -0
  90. package/dist/map-quality.js +56 -0
  91. package/dist/mapping-coverage.d.ts +87 -0
  92. package/dist/mapping-coverage.js +404 -0
  93. package/dist/model.d.ts +182 -0
  94. package/dist/model.js +66 -0
  95. package/dist/operation-benchmark-worker.d.ts +2 -0
  96. package/dist/operation-benchmark-worker.js +60 -0
  97. package/dist/operation-benchmark.d.ts +29 -0
  98. package/dist/operation-benchmark.js +1 -0
  99. package/dist/otel-metrics.d.ts +21 -0
  100. package/dist/otel-metrics.js +146 -0
  101. package/dist/performance-model.d.ts +185 -0
  102. package/dist/performance-model.js +396 -0
  103. package/dist/product-map.d.ts +69 -0
  104. package/dist/product-map.js +168 -0
  105. package/dist/provider-access.cjs +207 -0
  106. package/dist/provider-access.d.cts +14 -0
  107. package/dist/reports-cli.d.ts +1 -0
  108. package/dist/reports-cli.js +111 -0
  109. package/dist/reports-model.d.ts +27 -0
  110. package/dist/reports-model.js +39 -0
  111. package/dist/reports.d.ts +23 -0
  112. package/dist/reports.js +223 -0
  113. package/dist/repository-map.d.ts +22 -0
  114. package/dist/repository-map.js +151 -0
  115. package/dist/resource-cache.d.ts +17 -0
  116. package/dist/resource-cache.js +65 -0
  117. package/dist/review-cli.d.ts +19 -0
  118. package/dist/review-cli.js +224 -0
  119. package/dist/review.d.ts +48 -0
  120. package/dist/review.js +289 -0
  121. package/dist/runtime-metrics.d.ts +26 -0
  122. package/dist/runtime-metrics.js +290 -0
  123. package/dist/scope.d.ts +12 -0
  124. package/dist/scope.js +94 -0
  125. package/dist/sentry-activity.d.ts +39 -0
  126. package/dist/sentry-activity.js +174 -0
  127. package/dist/sentry.d.ts +130 -0
  128. package/dist/sentry.js +369 -0
  129. package/dist/service-release.d.ts +16 -0
  130. package/dist/service-release.js +14 -0
  131. package/dist/setup-cli.d.ts +2 -0
  132. package/dist/setup-cli.js +52 -0
  133. package/dist/setup-kit.cjs +163 -0
  134. package/dist/setup-kit.d.cts +32 -0
  135. package/dist/source-index.d.ts +37 -0
  136. package/dist/source-index.js +166 -0
  137. package/dist/source-review-git.d.ts +7 -0
  138. package/dist/source-review-git.js +103 -0
  139. package/dist/source-review.d.ts +16 -0
  140. package/dist/source-review.js +493 -0
  141. package/dist/telemetry.d.ts +17 -0
  142. package/dist/telemetry.js +51 -0
  143. package/dist/time-window.d.ts +9 -0
  144. package/dist/time-window.js +35 -0
  145. package/dist/trace-evidence.d.ts +23 -0
  146. package/dist/trace-evidence.js +55 -0
  147. package/dist/trace-model.d.ts +26 -0
  148. package/dist/trace-model.js +1 -0
  149. package/dist/tracing.d.ts +44 -0
  150. package/dist/tracing.js +123 -0
  151. package/dist/work-check.d.ts +17 -0
  152. package/dist/work-check.js +110 -0
  153. package/dist/work-cli.d.ts +1 -0
  154. package/dist/work-cli.js +148 -0
  155. package/dist/work-context.d.ts +57 -0
  156. package/dist/work-context.js +568 -0
  157. package/dist/work-intents.d.ts +6 -0
  158. package/dist/work-intents.js +140 -0
  159. package/dist/work-items.d.ts +58 -0
  160. package/dist/work-items.js +86 -0
  161. package/dist/work-model.d.ts +110 -0
  162. package/dist/work-model.js +261 -0
  163. package/dist/work-review-git.d.ts +8 -0
  164. package/dist/work-review-git.js +111 -0
  165. package/dist/work-review.d.ts +26 -0
  166. package/dist/work-review.js +426 -0
  167. package/dist/work-switcher-model.d.ts +43 -0
  168. package/dist/work-switcher-model.js +79 -0
  169. package/dist/work-switcher.d.ts +6 -0
  170. package/dist/work-switcher.js +171 -0
  171. package/dist/working-cli.d.ts +1 -0
  172. package/dist/working-cli.js +33 -0
  173. package/dist/working-code.d.ts +74 -0
  174. package/dist/working-code.js +421 -0
  175. package/dist/workspace-notes.d.ts +71 -0
  176. package/dist/workspace-notes.js +177 -0
  177. package/dist/workspace-tests.d.ts +21 -0
  178. package/dist/workspace-tests.js +573 -0
  179. package/package.json +547 -4
  180. package/src/activity-volume.ts +149 -0
  181. package/src/annotations.ts +481 -0
  182. package/src/benchmark-cli.ts +118 -0
  183. package/src/benchmark-worker.ts +22 -0
  184. package/src/benchmarks.ts +493 -0
  185. package/src/bin.ts +54 -0
  186. package/src/block-cli.ts +106 -0
  187. package/src/block-documents.ts +117 -0
  188. package/src/change-impact.ts +280 -0
  189. package/src/check-source.ts +82 -0
  190. package/src/checks-model.ts +108 -0
  191. package/src/cli.ts +440 -0
  192. package/src/code-model.ts +159 -0
  193. package/src/code-store.ts +98 -0
  194. package/src/compare-artifact.ts +314 -0
  195. package/src/compare.ts +440 -0
  196. package/src/compiler.ts +1326 -0
  197. package/src/compose.ts +94 -0
  198. package/src/core.ts +357 -0
  199. package/src/coverage-cli.ts +52 -0
  200. package/src/declaration-sources.ts +69 -0
  201. package/src/declared-graph.ts +74 -0
  202. package/src/display-name.ts +8 -0
  203. package/src/error-heat.ts +161 -0
  204. package/src/evidence.ts +94 -0
  205. package/src/factory-graph.ts +378 -0
  206. package/src/factory-model.ts +73 -0
  207. package/src/git-code.ts +461 -0
  208. package/src/git-refs.ts +43 -0
  209. package/src/history-activity.ts +146 -0
  210. package/src/history-churn.ts +416 -0
  211. package/src/history-git.ts +163 -0
  212. package/src/history-ledger.ts +636 -0
  213. package/src/history-ownership.ts +116 -0
  214. package/src/history-source.ts +117 -0
  215. package/src/integrations-cli.ts +187 -0
  216. package/src/issue-cache.ts +96 -0
  217. package/src/issue-cli.ts +137 -0
  218. package/src/issue-links.ts +153 -0
  219. package/src/linear-issues.ts +154 -0
  220. package/src/local-runtime.ts +70 -0
  221. package/src/map-activity.ts +309 -0
  222. package/src/map-model.ts +213 -0
  223. package/src/map-quality.ts +61 -0
  224. package/src/mapping-coverage.ts +570 -0
  225. package/src/model.ts +221 -0
  226. package/src/operation-benchmark-worker.ts +60 -0
  227. package/src/operation-benchmark.ts +28 -0
  228. package/src/otel-metrics.ts +176 -0
  229. package/src/performance-model.ts +575 -0
  230. package/src/product-map.ts +236 -0
  231. package/src/provider-access.cjs +207 -0
  232. package/src/provider-access.d.cts +14 -0
  233. package/src/reports-cli.ts +125 -0
  234. package/src/reports-model.ts +73 -0
  235. package/src/reports.ts +276 -0
  236. package/src/repository-map.ts +189 -0
  237. package/src/resource-cache.ts +76 -0
  238. package/src/review-cli.ts +256 -0
  239. package/src/review.ts +376 -0
  240. package/src/runtime-metrics.ts +386 -0
  241. package/src/scope.ts +103 -0
  242. package/src/sentry-activity.ts +234 -0
  243. package/src/sentry.ts +545 -0
  244. package/src/service-release.ts +18 -0
  245. package/src/setup-cli.ts +58 -0
  246. package/src/setup-kit.cjs +163 -0
  247. package/src/setup-kit.d.cts +32 -0
  248. package/src/source-index.ts +205 -0
  249. package/src/source-review-git.ts +129 -0
  250. package/src/source-review.ts +637 -0
  251. package/src/telemetry.ts +68 -0
  252. package/src/time-window.ts +51 -0
  253. package/src/trace-evidence.ts +80 -0
  254. package/src/trace-model.ts +26 -0
  255. package/src/tracing.ts +165 -0
  256. package/src/work-check.ts +143 -0
  257. package/src/work-cli.ts +195 -0
  258. package/src/work-context.ts +713 -0
  259. package/src/work-intents.ts +196 -0
  260. package/src/work-items.ts +151 -0
  261. package/src/work-model.ts +400 -0
  262. package/src/work-review-git.ts +130 -0
  263. package/src/work-review.ts +573 -0
  264. package/src/work-switcher-model.ts +121 -0
  265. package/src/work-switcher.ts +191 -0
  266. package/src/working-cli.ts +38 -0
  267. package/src/working-code.ts +582 -0
  268. package/src/workspace-notes.ts +203 -0
  269. package/src/workspace-tests.ts +654 -0
  270. package/toolkit/GUIDE.md +305 -0
  271. package/toolkit/SKILL.md +131 -0
  272. package/toolkit/bin/fractory +2 -0
  273. package/toolkit/build.json +1 -0
@@ -0,0 +1,305 @@
1
+ # Fractory: repository setup and developer guide
2
+
3
+ Fractory turns a repository into a navigable map of logical black boxes. Open a block to see its parts, inspect how they interact, read its documentation, run its tests and review changes on the same map. The repository remains the source of truth; Fractory does not replace Git, the test runner or your observability backend.
4
+
5
+ ## 1. Install and open a repository
6
+
7
+ Use the Mac app supplied by your team. Move Fractory.app to Applications before opening it. This private beta requires macOS 13 or newer and the build matching your Mac (arm64 for Apple Silicon; x64 for Intel). Unsigned beta builds may require an explicit exception in System Settings → Privacy & Security after attempting to open them. Follow your team's installation policy; never disable Gatekeeper globally. Signed, notarized releases avoid this setup friction.
8
+
9
+ Choose Open folder and select a local Git checkout. Fractory automatically installs its agent skill in `.agents/skills/fractory/SKILL.md`, including this guide as a reference. Existing team-customized skills are preserved. Three screens introduce the skill, offer agent-driven integration setup, and show how to ask your agent to map the product. Copy a focused `$fractory` request into Codex in this repository. No application dependencies or application modules are executed just by selecting a folder. The screen notices when the agent has generated a valid map and offers Open map. Existing mapped repositories remain directly accessible from the repository list.
10
+
11
+ The app includes its server and runtime. Git must be installed for history and comparisons. Executable tests require the repository's supported Bun or Node/Vitest toolchain and installed dependencies. GitHub CLI (`gh`) is optional if using a GitHub token or an agent's connected GitHub account.
12
+
13
+ ## 2. Find the bundled CLI and install the SDK
14
+
15
+ With the app in Applications, the CLI is:
16
+
17
+ ```sh
18
+ "/Applications/Fractory.app/Contents/Resources/toolkit/bin/fractory" doctor
19
+ "/Applications/Fractory.app/Contents/Resources/toolkit/bin/fractory" setup
20
+ "/Applications/Fractory.app/Contents/Resources/toolkit/bin/fractory" guide
21
+ ```
22
+
23
+ Run these from the repository root. The setup prompt contains the exact path when the app is elsewhere. In the commands below, `fractory` means this executable, or an existing repository script wrapping it. Adding its `bin` directory to your shell's PATH is optional. The CLI uses the app's embedded runtime; Node is not required just to inspect or compile a map.
24
+
25
+ Install the public CLI and annotation SDK with the repository's package manager:
26
+
27
+ ```sh
28
+ npm install @granular-software/fractory
29
+ npx fractory setup --install-skill
30
+ npx fractory doctor
31
+ ```
32
+
33
+ Bun, pnpm and Yarn can install the same package. Use the pinned local package for compiler/CI consistency. The Mac app also carries the identical package as `Contents/Resources/toolkit/fractal-sdk.tgz` for offline use. No Granular service is needed. Node 22+ runs the CLI; tests and benchmark subprocesses use the repository's own runners.
34
+
35
+ ## 3. Map the product without restructuring it
36
+
37
+ Inspect the real entry points, services, public APIs and tests first. Cover the largest product areas and their immediate parts before mapping one workflow deeply. Organize around responsibilities: importing data, storing it, exposing it, authorizing access. Folder names and deployment units are evidence, not automatically the logical hierarchy.
38
+
39
+ Use only the existing annotations: **Block** for a black box, **Interface** for a named way to interact with it, **Method** for an existing callable exposed through an interface, and **Process** for an existing multi-step operation. Processes can contain smaller blocks. Hosting and infrastructure stay separate from logical nesting. Contracts, auth, docs, tests and benchmarks attach to the relevant declaration.
40
+
41
+ Annotate existing classes and methods. TypeScript does not support decorators on standalone function declarations; use the equivalent function wrapper there. Do not introduce classes solely to make the map, list children manually, duplicate interface method lists, or maintain an independent graph.
42
+
43
+ ```ts
44
+ import { Block, Interface, Method, Process, type InterfaceRef }
45
+ from '@granular-software/fractory/annotations';
46
+
47
+ // Existing application class: its name and implementation remain yours.
48
+ @Block('catalog', { label: 'Catalog', description: 'Store and retrieve products.' })
49
+ export class Catalog {
50
+ @Interface({ label: 'Read products', docs: './catalog.md', tests: ['./catalog.test.ts'] })
51
+ static readonly read: InterfaceRef;
52
+
53
+ @Interface({ label: 'Update products' })
54
+ static readonly write: InterfaceRef;
55
+
56
+ @Method(() => Catalog.read)
57
+ async get(id: string) { /* existing implementation */ return { id }; }
58
+
59
+ @Method(() => Catalog.write)
60
+ async save(id: string) { /* existing implementation */ return { id }; }
61
+ }
62
+ ```
63
+
64
+ In a different file, keep an existing standalone operation and give it a typed parent:
65
+
66
+ ```ts
67
+ import { Method, Process } from '@granular-software/fractory/annotations';
68
+ import { Catalog } from './catalog';
69
+
70
+ export const importProducts = Process('catalog/import', {
71
+ parent: () => Catalog,
72
+ label: 'Import products',
73
+ description: 'Validate and save an incoming product batch.',
74
+ })(async function importProducts(catalog: Catalog, ids: string[]) {
75
+ for (const id of ids) await catalog.save(id);
76
+ });
77
+
78
+ export const findProduct = Method(() => Catalog.read)(
79
+ async function findProduct(catalog: Catalog, id: string) { return catalog.get(id); }
80
+ );
81
+ ```
82
+
83
+ Use stable IDs that survive file moves. Parent references and interface references may cross files. The compiler reconstructs membership, contracts and statically resolvable calls without importing application modules. Dynamic dispatch, HTTP, queues and WebSockets may not resolve automatically. Leave unverified relationships as gaps; a typed contract alone is not proof that two services communicate. Document evidence and limits rather than inventing arrows.
84
+
85
+ Runtime argument/result validation is optional and explicit: `@Method(() => Catalog.write, { contract: { args: argumentSchema, result: resultSchema } })`. Both schemas implement synchronous `parse`. Interface `auth` receives `{ receiver, args, context }`; retain existing authorization and use trusted host context if adding a policy. TypeScript contracts describe shapes; runtime validation and application tests enforce behavior. Do not silently add a different auth policy during mapping.
86
+
87
+ ## 4. Generate, verify and keep the map current
88
+
89
+ ```sh
90
+ fractory compile --include src --graph --write fractory.json
91
+ fractory compile --include src --graph --write fractory.json --check
92
+ fractory check
93
+ fractory quality --json
94
+ fractory coverage --missing --json
95
+ fractory open
96
+ ```
97
+
98
+ Use comma-separated source directories in `--include`, such as `apps,packages,src,lib`, and keep the same selection when generating and checking. No annotations is a setup gap, not a successful empty map. `compile --check` compares current compiler output with the saved artifact without rewriting it. `check` validates the saved definition; it does not run tests. `quality` identifies structural problems, missing purpose and absent mapped interactions. No mapped interaction is not proof of dead code.
99
+
100
+ Commit `fractory.json`, annotations and documentation. Add generation and check scripts to the repository. In CI, run the same compiler version with the same include paths and fail on stale output. Use the repository's normal toolchain and pinned SDK/compiler source for CI; the Mac executable itself is not a Linux CI dependency. The public package includes the compiled Node CLI (for example `npx fractory compile --include src --graph --write fractory.json --check`). Existing Granular repositories can keep their three generated artifacts and their existing generation/check scripts; do not replace them with a shallow standalone map.
101
+
102
+ Map coverage measures ownership of in-scope TS/JS source lines, not test coverage. Review missing source in the coverage browser. Discard generated files, vendored libraries or other irrelevant regions with an explicit reason. Do not discard real product behavior to improve the percentage. Other languages can be viewed using an externally generated definition, but this compiler's decorator and coverage discovery is for TS/JS; do not promise equivalent automatic support for every language.
103
+
104
+ ## 5. Navigate and work on a block
105
+
106
+ The map is the primary workspace. Click into a block to see its contents; zoom through nested blocks or use the breadcrumb to go up. Outside callers stay distinguishable from inside parts. Leaf blocks open their details rather than an empty internal map. `⌘K` searches names and logical paths. `⌘B` toggles the block workspace; `⌘⇧H` returns to the product root (use Control instead of Command on other keyboards). Search and Workspace form one toolbar group; Metrics, Benchmarks, Worktrees, History, Sentry and Linear form a separate map group. Display settings control zoom behavior and visual density.
107
+
108
+ A block’s About view and its open map show available activity: saved local changes, errors, linked issues, code activity and named performance measurements. Click a signal to open its evidence. They reuse the overlay data and selected periods; cached, partial or unavailable sources remain explicit. Disconnected sources do not appear as healthy zeros. Historical comparisons do not borrow today’s runtime signals.
109
+
110
+ Open a block workspace for its purpose, interfaces/contracts, Connections, Notes, Tests, History and available performance evidence. Large workspace collections use Arc tree navigation grouped by logical block ownership. Direct attachments sit at the current level; shared items appear once at their common parent, with their associations retained. Search by item or block, expand a branch, and select an item to read its content. Test branch checkboxes select all runnable suites beneath them; arrow keys navigate, Space checks a row and Enter opens it. Checks inside a suite follow its real describe groups. Commits remain chronological and are grouped by month. Called by shows actual mapped incoming relationships; highlight them directly on the map. These callers are places to inspect after an interface change, not a list of proven breakages.
111
+
112
+ Right-click a block for navigation and copy actions. `⌘⇧C` copies its ID, name and source link for a Codex chat. `File → Copy Map Link` copies the current map/comparison context. Desktop links currently include the local repository path: colleagues with a different checkout location should open their own repository and navigate by the copied block ID or use Compare. Do not treat machine-local paths as universally portable links.
113
+
114
+ Markdown notes are versioned files attached to blocks, displayed as readable content and editable in the workspace. Use them for purpose, design decisions, maintenance notes and known limits. Link related attached pages and relevant blocks. Keep secrets and production payloads out of notes. Avoid a second architecture document duplicating generated contracts.
115
+
116
+ ### Agent reports
117
+
118
+ Reports are repository Markdown documents tied to one or several real block IDs. Use them for findings, reviews, explanations and handoffs that the developer should read in Fractory. They are separate from editable block notes. No extra graph declaration is needed.
119
+
120
+ ```sh
121
+ fractory reports create --block BLOCK_ID --title 'Review findings' --file /tmp/review.md --author Codex
122
+ fractory reports create --block FIRST_ID --block SECOND_ID --title 'Shared finding' --stdin
123
+ fractory reports list --block BLOCK_ID --unread
124
+ fractory reports show REPORT_ID
125
+ fractory reports open REPORT_ID
126
+ fractory reports read REPORT_ID
127
+ fractory reports unread REPORT_ID
128
+ ```
129
+
130
+ `--stdin` reads piped Markdown, not an interactive editor. `--root PATH` selects a checkout; `--file` is relative to the agent's current directory. Creation checks every block ID and returns the document plus a `fractory://` link that opens its reader. A report is an ordinary `.md` file in `docs/fractory/reports/`, with a small `fractory` front-matter mapping containing its ID, title, target IDs, creation date, optional author label and checkout HEAD. HEAD is context, not proof of an unchanged checkout or an executed test. Commit reports when they belong with the work; creation does not commit or publish anything.
131
+
132
+ A blue card badge counts unread reports on that block and its nested parts. The same report counts once at a common parent, even when attached to several children. The current map heading exposes the repository/focused-block inbox. Workspace → Docs → Reports uses the logical block tree and displays full Markdown. Source HTML and automatic remote images are disabled, as for notes.
133
+
134
+ Opening report content acknowledges that content revision for this developer. Read receipts stay in the ignored `.fractal/reports/read/` directory, separate from shared reports. CLI list/show does not acknowledge anything. Mark unread is available in the reader and CLI; a content edit also makes the report unread again. Reports with removed targets remain in the repository's Unassigned group. Historical map comparisons do not borrow today's notification badges.
135
+
136
+ ## 6. Run real tests and inspect results
137
+
138
+ Attach existing test suites using `tests: ['./relative.test.ts']`. Fractory resolves paths relative to the declaring file and supports associated Bun and Vitest suites. In Tests, inspect named cases and source, select suites, run them, and read assertion failures and actual runner output. Install repository dependencies before running; opening or listing tests does not execute them.
139
+
140
+ ```sh
141
+ fractory block BLOCK_ID --docs
142
+ fractory tests --block BLOCK_ID --source
143
+ fractory tests --block BLOCK_ID --file src/catalog.test.ts --run
144
+ ```
145
+
146
+ All runnable suites are selected by default. Use Select all or Clear selection to choose a subset. The runner queues the full selection in bounded batches; Stop cancels the active batch and remaining queue. An attached suite is an association, not a claim that every method, branch or caller is covered. Passing results apply to the source/environment actually tested and become stale as code changes. Fractory does not invent tests from the map or start deployment/end-to-end tests implicitly.
147
+
148
+ ## 7. Local Git, history and conceptual PR review
149
+
150
+ **Worktrees** opens the branch/worktree picker. Open one to see its blue context bar, current reports and results. **Show worktree changes** highlights committed and uncommitted edits against its starting revision. Git identifies worktrees and files, not which agent typed each line. Refresh does not require a commit. Keep untracked, staged, unstaged and committed changes distinct.
151
+
152
+ History is activity over a selected time window. Revision comparison is the difference between two versions; edits later reverted can count as activity but disappear in an endpoint diff. Read the visible mode, date range, attribution and unassigned/excluded totals. Churn is added plus deleted lines divided by the relevant starting size; it is not net growth and can exceed 100%. Changed lines do not measure quality or developer productivity.
153
+
154
+ Compare opens a picker for GitHub PRs, local branches, revisions and uncommitted work. Review changes hierarchically: product areas first, then interfaces and internal changes. Historical contracts and connections can be compared exactly only when maps/snapshots exist at both revisions. Otherwise Fractory labels a current-map footprint; it must not claim to know the old architecture. Keep generated definitions in commits and CI artifacts for future reviews.
155
+
156
+ ```sh
157
+ fractory review --base main --head HEAD --open
158
+ fractory review --pr 123 --open
159
+ fractory review --base BASE_SHA --head HEAD_SHA --title 'PR title' --url https://github.com/owner/repo/pull/123 --open
160
+ ```
161
+
162
+ The CLI prints the selected immutable refs and a desktop link. `--pr` uses your signed-in `gh` account; an agent can instead use its GitHub connector and pass resolved SHAs. Fetch only missing selected refs/ancestry when needed. Do not check out a PR, create worktrees or scan all history just to view it. The comparison does not include uncommitted work unless that source is explicitly selected.
163
+
164
+ ## 8. Connect each repository's integrations
165
+
166
+ Ask `$fractory Connect GitHub, Sentry and Linear for this repository.` The agent handles discovery, provider authorization and verification. You handle unavoidable account login/MFA/consent only. Credentials are encrypted on this Mac, outside Git, separately for each repository. No tokens belong in chat, source, a URL or shell arguments.
167
+
168
+ ```sh
169
+ fractory integrations status
170
+ fractory integrations connect all --auto
171
+ fractory integrations connect github --login
172
+ fractory integrations connect sentry --login --org ORG --projects PROJECT_A,PROJECT_B
173
+ fractory integrations connect linear --token-stdin --workspace-id WORKSPACE_ID
174
+ fractory integrations check all
175
+ fractory integrations disconnect linear
176
+ ```
177
+
178
+ `--auto` reuses saved credentials, provider CLI sessions and allowlisted repository environment values. Read access is verified before saving. GitHub is checked against the chosen repository, Sentry against the selected organization/projects, and Linear against its actual workspace. Ambiguous selection or missing authorization is a structured agent task, not a successful connection. `--token-stdin` is for a secure agent-owned pipe; never ask the user to paste a key. Status is redacted. The CLI uses a private local channel to the Mac app; the repository must be registered. Advanced settings remain in Integrations (`⌘,`).
179
+
180
+ **GitHub:** use the official `gh` browser login. The CLI derives owner/repository from the Git remote where possible. Organization SSO may need consent. Verify an actual PR appears in Compare. Local Git works independently of GitHub.
181
+
182
+ **Sentry:** the new official `sentry` CLI supports read-only browser authorization; this differs from legacy `sentry-cli`. Keep OAuth refresh owned by that CLI. Existing `SENTRY_AUTH_TOKEN`, repository settings or standard legacy CLI credentials can also be reused. Select this repository's project slugs explicitly; don't attach every organization project. Reliable leaf-block assignment requires deployed release/commit IDs and original source frames. Source-map upload credentials belong in CI. Unresolved frames and missing historical maps remain unmatched. Automatic setup targets sentry.io; self-hosted installations need existing server-side host configuration and direct credentials.
183
+
184
+ **Linear:** reuse saved Fractory access or `LINEAR_API_KEY`. Otherwise the agent verifies the browser account/workspace and acquires read-only access in Security & access, then hands the credential to the CLI via stdin. Codex's own OAuth credential is not exportable Fractory access. Lack of workspace membership remains an explicit blocker. Link issues to real block IDs in `fractal.issues.json`; titles alone cannot reliably assign them. Recorded imports are snapshots, not automatic refresh. Onboarding does not create external issues or send messages.
185
+
186
+ **Metrics:** optional Prometheus-compatible read endpoint (including Grafana Cloud), environment, username if using Basic auth and read token. Keep telemetry write credentials in the product's runtime/CI configuration. A successful query connection does not prove that the expected instruments are arriving. Verify real recent samples for a relevant block, correct units and environment, plus source freshness. No data is not zero. Native Cloudflare log/trace export alone does not establish custom application metrics.
187
+
188
+ These providers are optional: first get a useful map, documentation, tests and local Git working, then enable available connections. A disconnected provider should remain clearly disconnected, not break navigation or claim a healthy zero.
189
+
190
+ ## 9. Benchmarks and metrics
191
+
192
+ Benchmarks repeat a fixed workload; metrics observe real traffic. Attach ordinary `.bench.ts` files to relevant blocks with `benchmarks: ['./example.bench.ts']`. Product benchmarks export an operation with a name, versioned fixture, `prepare`, `run`, `cleanup`, and an identified test environment/revision. Setup and cleanup stay outside the measured operation. Verify correctness and preserve failed attempts. Compare matching fixtures, workloads, timing sources and environment configuration. Repeated runs with too much variance are inconclusive, not an automatic regression. Small sample sets do not justify a meaningful p95. Function microbenchmarks can use Tinybench; do not present them as end-to-end product timings.
193
+
194
+ ```sh
195
+ fractory benchmark --block BLOCK_ID --json
196
+ fractory benchmark --block BLOCK_ID --file src/example.bench.ts --run
197
+ fractory benchmark --compare SELECTED_RUN_ID --against REFERENCE_RUN_ID --json
198
+ ```
199
+
200
+ Select two runs in the block workspace to compare measured duration, individual attempts and phases. Same-deployment comparisons are labeled repeatability checks. A parent shows named measurements, not a combined score. Only run remote benchmarks against an explicitly approved test target. Existing Granular fixtures or deployments are not defaults for other repositories. Dedicated infrastructure provisioning and performance comparisons across deployed revisions require their own product-specific setup and verification.
201
+
202
+ Live metrics should measure named outcomes: build queue wait versus execution, usable-session preparation, import throughput/backlog, query latency, action failures. Use standard OpenTelemetry counters/histograms/gauges and an existing telemetry backend. Attach read queries using `fractory.metrics.json`. For example, after verifying that your backend really publishes `catalog_queue_depth` with an `environment` label:
203
+
204
+ ```json
205
+ {
206
+ "schema": "fractory.metrics.v1",
207
+ "gauges": [{
208
+ "id": "catalog-backlog",
209
+ "label": "Products waiting to import",
210
+ "unit": "products",
211
+ "aggregation": "sum",
212
+ "sources": [{ "block": "catalog/import", "query": "sum(catalog_queue_depth{environment=$environment})" }]
213
+ }]
214
+ }
215
+ ```
216
+
217
+ Use an actual mapped ID and metric name. `$environment` is substituted by Fractory using the selected metrics environment. Sum only additive measurements such as disjoint queue inventories; never sum unrelated latencies. The current query adapter also supports `max`, with visible semantics when measurements roll up to parents. Keep the file small: currently at most 12 measurements and 20 source queries in total.
218
+
219
+ The SDK exports `otel-metrics` and `telemetry` for supported Node/Cloudflare hosts. Avoid payloads, object IDs and unbounded metric labels. Queue depth comes from authoritative queue/storage state. Metrics and benchmark UI are still beta; do not claim production verification, automatic PR performance comparison or statistical guarantees beyond actual recorded evidence.
220
+
221
+ ## 10. Working with agents and maintaining the installation
222
+
223
+ ```sh
224
+ fractory setup --install-skill
225
+ ```
226
+
227
+ This installs `.agents/skills/fractory/SKILL.md` only if no skill exists. Read and merge an existing skill deliberately; never overwrite team guidance automatically. An agent can use the same block IDs, Markdown, real test results and comparison URLs as the human map. Ask it to start with a block's context and real connections, make the change, regenerate/check the map, then run relevant tests. No separate binding registry or agent-only architecture is needed.
228
+
229
+ Repository annotations, generated maps, notes and issue links travel through Git. Each person configures their own provider access on their own Mac. Updating Fractory replaces the app in Applications while keeping recent repositories and encrypted settings in `~/Library/Application Support/Fractory`. Updates are manual in this beta; no public upload, automatic updater or team credential synchronization is implied. Keep the old app until a new build is verified.
230
+
231
+ Help → Show Logs helps diagnose startup issues; review logs before sharing them. Reopen a repository after changing environment files. Fractory does not need the Granular dashboard or a dev server running. If the map is missing/stale, regenerate it; if a runner is missing, install the repository's required toolchain; if a provider fails, use Save & check and verify actual provider data. Report remaining gaps plainly.
232
+
233
+ ## Setup is complete when
234
+
235
+ - The product's largest areas and their immediate parts are understandable on the map, with verified callers and explicit gaps.
236
+ - Generated output is reproducible and stale output fails a CI check.
237
+ - At least one attached Markdown document renders and one real existing test runs with named results.
238
+ - A saved local edit appears in its worktree view and a meaningful comparison opens with its evidence limits visible.
239
+ - Available connectors have been checked against actual repository/project data; unavailable ones remain explicitly disconnected.
240
+ - Each enabled metric/benchmark has a clear meaning, source, environment and reproducible definition. Unconfigured optional features are recorded as gaps, not fake successes.
241
+
242
+ References: [Fractory's standard metrics model](https://opentelemetry.io/docs/concepts/signals/metrics/), [GitHub fine-grained tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens), [Sentry authentication](https://docs.sentry.io/api/auth/), [Linear authentication](https://linear.app/developers/graphql), [Mac app installation](https://support.apple.com/102445).
243
+
244
+ ## Start work from the map
245
+
246
+ Main is the reference view. Cmd/Ctrl-click blocks at any level, choose **Start worktree**, name the work, then **Copy full brief** in the blue work bar. The branch and worktree form one work context. An existing worktree can be selected from Main → Worktrees. Proposed blocks and links are dashed intentions, not compiled code.
247
+
248
+ ```sh
249
+ fractory work list
250
+ fractory work create --title 'Improve build reuse' --block BLOCK_ID
251
+ fractory work show WORK_ID
252
+ fractory work handoff WORK_ID
253
+ fractory work plan WORK_ID --file plan.json --revision REVISION
254
+ fractory work check WORK_ID
255
+ fractory work review WORK_ID
256
+ fractory work open WORK_ID
257
+ ```
258
+
259
+ Work in the exact directory returned by `work create` or the handoff. Do not switch the original checkout or create another worktree for the same request. Read its scope and proposed changes before editing. Parent scope includes descendants; the work plan lives in `docs/fractory/work/WORK_ID.json`. Change it through `work plan` with the current revision from `work show`, preserving unrelated proposals. The plan JSON contains `proposals` and optional `scope`; proposals have a `proposal:UUID` ID, kind `block`, `connection`, or `annotation`, a label and note. Blocks specify `parent`; connections specify `source` and `target`; annotations specify `target` and `change` (`change` or `remove`). References are stable block/proposal IDs. Do not manually add these intentions to the compiled map.
260
+
261
+ Implement the intent using the existing code/decorators, regenerate the real map, run the actual associated tests and `work check` before committing. This command exits nonzero for outside, shared or unassigned files. Existing files use pinned baseline ownership, so editing the map cannot silently claim them. File-level ownership is conservative and is not a filesystem sandbox or a protected merge check. Report uncertainty and request a scope adjustment when necessary; do not hide it by remapping unrelated files. To enforce a merge policy, the repository must run the check in its trusted CI using the pinned baseline, independently of agent-edited plan files.
262
+
263
+ Create reports from inside that worktree. Its tests, benchmark results, local changes and report inbox remain separate. Production telemetry is not borrowed by an undeployed branch. Main reads committed notes/reports; when the base predates a committed map, the interface labels the reviewed-map fallback and cannot prove historical contracts. A copied bootstrap map must be regenerated before claiming current code alignment.
264
+
265
+ The Mac app detects the branch’s PR automatically through the repository’s GitHub connection. Its number, title and Draft/Open/Merged/Closed state appear as a direct GitHub link in the blue worktree bar. Detection checks the exact head repository and remote branch, including forks and unpushed local changes; it refreshes in the background while the app is visible. Several open matches remain a choice. No match adds no control; an unavailable GitHub connection offers Integrations. No URL-pasting step is required. Existing `work pr` records remain readable for compatibility, but they are not treated as verified GitHub state. `work review` returns a Markdown review summary and a deep link for the PR description; publish it only within the user's authorized PR workflow. The deep link needs the developer's local repository/work context; it is not a hosted public preview. Legacy immutable revision/PR comparisons remain available through `fractory review`.
266
+
267
+ ### Planning in an existing checkout
268
+
269
+ Open **Worktrees** and choose the existing checkout. Use the blue canvas tools or right-click a block to add it to the work. Fractory attaches the plan to that checkout without changing its branch, staged changes or local files. CLI equivalent: `fractory work adopt TREE_ID --block BLOCK_ID`.
270
+
271
+ Comments stay attached to their target, support replies and can be resolved or reopened. Cmd/Ctrl-Z and Shift-Cmd/Ctrl-Z undo and redo your plan edits; native text-field undo remains unchanged. External agent plan edits clear local undo history to avoid overwriting them. Copy full brief is a fresh complete snapshot, including replies and resolved comments; old clipboard copies do not update.
272
+
273
+ **Show worktree changes** compares the starting Git revision with saved code. Filter Implementation, Interfaces or Connections to highlight the map. The evidence tree follows logical block nesting and shows changed declarations. Needs checking contains stale anchors, inferred returns and changed unresolved calls; unassigned code remains accounted for. This bounded analysis does not execute code or claim dynamic dispatch or full type compatibility. Unchanged polls reuse review results and immutable Git blobs.
274
+
275
+ Blue controls act on the worktree. Neutral **Metrics** and **Sentry** buttons return to Main before opening production data; their tooltips identify this context.
276
+
277
+ ### Finding current work
278
+
279
+ **Worktrees** opens a compact switcher. Recent shows up to eight active or planned contexts and work opened or edited in the last 30 days. Older checkouts remain under Worktrees. Search by a work name, block, branch or checkout path; use arrow keys and Enter to open. **Worktrees** includes every local checkout, while **Branches** exposes branches without a checkout and marks them read-only. **Main** returns to the reference map. Names and commit metadata appear first; cached local status follows. A Local edits label means saved Git changes, not proof that an agent is currently running. Unnamed detached worktrees show related blocks and their last commit; Fractory does not invent task titles.
280
+
281
+
282
+ ## Review intentions against implementation
283
+
284
+ The blue worktree view has a **Plan** section grouped by block. Select an intention, choose **Link implementation**, then pick its actual block or connection directly on the map. Confirm **Done**, or **Drop** an intention while keeping its original request. **Reopen** puts it back in the active plan. A completed sketch gives way to the linked real block; pending proposed connections follow that explicit link. Unfinished nested sketches retain their containing block.
285
+
286
+ **Done** records a confirmation and a fingerprint of the request, current mapped source and attached files. It is not a test pass or proof of behavior. A stale source reference must be regenerated before confirmation. Later changes to that request or implementation become **Needs recheck**; changes outside the linked source files do not invalidate it. Resolving a comment thread only closes the discussion. It does not mark an intention implemented.
287
+
288
+ ```sh
289
+ fractory work show WORK_ID
290
+ fractory work intent WORK_ID --proposal PROPOSAL_ID --status planned --implementation BLOCK_OR_CONNECTION_ID --revision REVISION
291
+ fractory work intent WORK_ID --proposal PROPOSAL_ID --status done --revision REVISION
292
+ fractory work intent WORK_ID --proposal PROPOSAL_ID --status dropped --revision REVISION
293
+ fractory work review WORK_ID
294
+ ```
295
+
296
+ Use the latest revision returned by each command. `work show`, `work handoff` and `work review` expose the same current states. Continue planned items and those needing recheck; keep done and dropped decisions as records. Existing local checks remain advisory; trusted CI and protected-branch enforcement are separate.
297
+
298
+
299
+ ## Canvas selection and drawing
300
+
301
+ Cmd/Ctrl-click selects a block and its descendants. Cmd/Ctrl-A selects the inside blocks at the current map level; outside connections are not selected. Text fields keep normal Select All behavior. The selected enclosure and its included children have blue rings. Cmd/Ctrl-click an included child to exclude its subtree, or select inside that exclusion to reinclude a smaller part. On Main, Start worktree keeps these rules. In a worktree, Update worktree selection saves staged scope changes; the context menu can also add or exclude a block directly.
302
+
303
+ Work plans store positive `scope` IDs and optional `excluded` IDs. The nearest ancestor rule wins. Preserve both through CLI plan updates; `work handoff` and `work check` use the same rules. A parent may remain in scope while a child is explicitly excluded.
304
+
305
+ The blue Block tool previews placement before a click. Name the block directly on the card. Connect by dragging blue handles or clicking a source and destination; name the connection on its wire. Enter or blur saves the name; Escape cancels a new unnamed sketch. Plan saves are ordered and show failures rather than silently discarding fast actions.
@@ -0,0 +1,131 @@
1
+ ---
2
+ name: fractory
3
+ description: Set up Fractory, connect GitHub/Sentry/Linear securely, map the product as nested logical blocks, inspect docs and real tests, and open conceptual branch/PR/local comparisons. Use for block-centered development and map freshness.
4
+ ---
5
+ <!-- fractory-managed-skill -->
6
+
7
+ # Fractory
8
+
9
+ Use stable block IDs, real source ownership and verified connections. Preserve existing functions, classes, files and package manager. Opening repository setup installs this skill automatically; do not make the user install it or import a map.
10
+
11
+ Find existing `fractal`/`fractory` repository scripts first. The Mac app also ships `/Applications/Fractory.app/Contents/Resources/toolkit/bin/fractory` (quote the full path); use its actual location if installed elsewhere. Examples below call it `fractory`.
12
+
13
+ Read [the complete guide](references/fractory-guide.md) for SDK syntax, compiler/CI, docs/tests, Git review, coverage, integrations, metrics and benchmarks. `fractory guide` also returns it.
14
+
15
+ ## First map
16
+
17
+ Run `fractory doctor`. Inspect the actual code and existing generation scripts. Map the whole product shallowly first, then nest logical responsibilities. Annotate existing code with blocks, interfaces, methods and processes; attach docs, executable tests and resources. No separate manual graph, duplicated method lists, invented callers or file-tree nesting. Unknown dynamic interactions remain gaps. Install the bundled portable SDK only if absent, reproducibly for teammates. Generate and verify the map, run a real test, add freshness checks to existing CI, then `fractory open`. Optional integrations do not block mapping or local Git.
18
+
19
+ ## Connect tools for the user
20
+
21
+ ```sh
22
+ fractory integrations status
23
+ fractory integrations connect all --auto
24
+ fractory integrations connect github --login
25
+ fractory integrations connect sentry --login --org ORG --projects PROJECT_A,PROJECT_B
26
+ fractory integrations check all
27
+ ```
28
+
29
+ The repository must be registered in Fractory. The CLI opens the Mac app when needed, discovers provider CLI logins and allowlisted repository environment credentials, verifies read access, and saves encrypted per-repository credentials through a private local channel. Status never includes tokens. GitHub and Sentry login use the official `gh` and new `sentry` CLIs; `sentry` is different from legacy `sentry-cli`. If missing, install the official CLI using its documented method. Request read-only scopes and let the CLI own OAuth refresh.
30
+
31
+ Treat structured connection failures as actions for you, not chores for the user. Verify the intended account, GitHub repository, Sentry organization/projects and Linear workspace. Do not guess between accounts or broaden permissions to get a green status. Only unavoidable login, MFA or provider consent belongs to the user.
32
+
33
+ For Linear, first reuse saved Fractory access or `LINEAR_API_KEY`. If absent, use browser automation to verify the signed-in account and workspace, then acquire approved read-only access in Security & access. A Codex connector OAuth credential is separate; never extract or repurpose it. Missing workspace membership is an explicit blocker, not a reason to create a workspace.
34
+
35
+ An agent-owned secure pipe can hand the acquired credential to Fractory:
36
+
37
+ ```sh
38
+ fractory integrations connect linear --token-stdin --workspace-id WORKSPACE_ID
39
+ ```
40
+
41
+ Never put tokens in command arguments, logs, transcripts, prompts, links, clipboard prompts, source files or Git. Do not echo a secret to the terminal. Prefer an in-memory pipe from the authorized credential source. If the environment cannot transfer it without disclosure, report that specific limitation instead of asking the user to paste a key. The CLI verifies workspace identity before saving. Verify real data after setup. Configured credentials, recorded snapshots and automatic refresh are different states. External issue creation, messages and product deployment require separate authorization.
42
+
43
+ ## Daily block work
44
+
45
+ ```sh
46
+ fractory block BLOCK_ID --docs
47
+ fractory tests --block BLOCK_ID --source
48
+ fractory tests --block BLOCK_ID --file PATH --run
49
+ fractory open --block BLOCK_ID
50
+ fractory review --pr NUMBER --open
51
+ fractory review --base main --head HEAD --open
52
+ fractory working --json
53
+ ```
54
+
55
+ Read Markdown content and named test results, not filenames alone. Test associations are not measured coverage. Prefer connected GitHub tools for immutable PR identities, otherwise use `gh`. Review without creating a worktree or checking out a PR; fetch only missing selected refs. Handle metadata as data with structured arguments or proper shell quoting. Verify the map link opens, and distinguish exact historical maps from current-map footprints.
56
+
57
+ After edits, run existing generation/check scripts and relevant tests. Standalone example:
58
+
59
+ ```sh
60
+ fractory compile --include src --graph --write fractory.json
61
+ fractory compile --include src --graph --write fractory.json --check
62
+ fractory quality --json
63
+ fractory coverage --missing --json
64
+ ```
65
+
66
+ Match actual include paths; preserve richer existing pipelines. Ownership coverage is not test coverage. Discard only reviewed irrelevant source with a reason. Metrics observe actual traffic; benchmarks repeat fixed workloads. Preserve missing data, failures and inconclusive comparisons.
67
+
68
+ ## Reports for developers
69
+
70
+ Write a report when the user asks for findings, a review or a handoff that should remain attached to the factory. Use ordinary Markdown and the CLI, without another binding list or manually constructed metadata.
71
+
72
+ ```sh
73
+ fractory reports create --block BLOCK_ID --title 'Review findings' --file /tmp/review.md --author Codex
74
+ fractory reports list --block BLOCK_ID --unread
75
+ fractory reports show REPORT_ID
76
+ fractory reports open REPORT_ID
77
+ ```
78
+
79
+ Choose the smallest meaningful existing block. Repeat `--block` only when a report really concerns several blocks. Parent badges roll up automatically and count a shared report once: do not attach every ancestor. State what you observed, relevant evidence, tests actually run and unresolved limits. Do not invent validation or include secrets. The create result includes its Markdown path and a reader deep link; optional `--open` displays it immediately.
80
+
81
+ Reports live in `docs/fractory/reports/` and can be committed with the work. The developer reads rendered Markdown from a card badge or Workspace → Docs → Reports. Opening the content marks that revision read locally; editing Markdown makes it unread again. CLI list/show never clear notifications. Use `fractory reports read REPORT_ID` or `unread REPORT_ID` only when the user asks to change read status. Removed targets remain visible in the repository inbox; use current stable IDs for new reports.
82
+
83
+ ## Start work from the map
84
+
85
+ Main is the reference view. Cmd/Ctrl-click blocks at any level, choose **Start worktree**, name the work, then **Copy full brief** in the blue work bar. The branch and worktree form one work context. An existing worktree can be selected from **Worktrees** in the toolbar. Adding a block or comment there attaches a plan in place; it does not create another branch or checkout. Proposed blocks and links are dashed intentions, not compiled code. Use the blue floating toolbar to place a block on the canvas, connect two cards, or attach a comment to a block. Right-click an existing block to add it to this worktree. **Copy full brief** always copies a fresh complete snapshot of the folder, branch, selected blocks, all proposals and attached comments. It never copies only a delta. Copy again after editing; an earlier clipboard or Codex message does not update automatically. **Check changed blocks** reports changed files outside the selected blocks or without clear ownership. **Show worktree changes** compares saved code with the starting revision. Implementation, interface declaration and proven connection changes can be highlighted separately. Change evidence is grouped by logical block, including before/after signatures. Stale anchors, inferred return types and dynamic or unmapped changed calls remain under Needs checking; this is not proof of full type compatibility. Fractory setup and incompletely mapped files remain visible separately.
86
+
87
+ ```sh
88
+ fractory work list
89
+ fractory work create --title 'Improve build reuse' --block BLOCK_ID
90
+ fractory work adopt TREE_ID --block BLOCK_ID
91
+ fractory work show WORK_ID
92
+ fractory work handoff WORK_ID
93
+ fractory work plan WORK_ID --file plan.json --revision REVISION
94
+ fractory work check WORK_ID
95
+ fractory work review WORK_ID
96
+ fractory work open WORK_ID
97
+ ```
98
+
99
+ Work in the exact directory returned by `work create` or the handoff. Do not switch the original checkout or create another worktree for the same request. Read its scope and proposed changes before editing. Parent scope includes descendants; the work plan lives in `docs/fractory/work/WORK_ID.json`. Change it through `work plan` with the current revision from `work show`, preserving unrelated proposals. The plan JSON contains `proposals` and optional `scope`; proposals have a `proposal:UUID` ID, kind `block`, `connection`, or `annotation`, a label and note. Blocks specify `parent`; connections specify `source` and `target`; annotations specify `target` and `change` (`change` or `remove`). Comments form a thread: each annotation has its own ID; optional `createdAt` and `resolved` preserve time and resolution. Multiple comments can target the same block or proposed connection. Undo/redo affects local plan edits only, never source code or external agent changes. References are stable block/proposal IDs. Do not manually add these intentions to the compiled map.
100
+
101
+ Implement the intent using the existing code/decorators, regenerate the real map, run the actual associated tests and `work check` before committing. This command exits nonzero for outside, shared or unassigned files. Existing files use pinned baseline ownership, so editing the map cannot silently claim them. File-level ownership is conservative and is not a filesystem sandbox or a protected merge check. Report uncertainty and request a scope adjustment when necessary; do not hide it by remapping unrelated files. To enforce a merge policy, the repository must run the check in its trusted CI using the pinned baseline, independently of agent-edited plan files.
102
+
103
+ Create reports from inside that worktree. Its tests, benchmark results, local changes and report inbox remain separate. Blue toolbar actions follow the current worktree. Neutral Metrics and Sentry buttons open deployed data on Main; production telemetry is not borrowed by an undeployed branch. Main reads committed notes/reports; when the base predates a committed map, the CLI records that structure comes from a reviewed fallback; historical contracts cannot be proved. A copied bootstrap map must be regenerated before claiming current code alignment.
104
+
105
+ The Mac app detects the branch’s PR automatically through the repository’s GitHub connection. Its number, title and Draft/Open/Merged/Closed state appear as a direct GitHub link in the blue worktree bar. Detection checks the exact head repository and remote branch, including forks and unpushed local changes; it refreshes in the background while the app is visible. Several open matches remain a choice. No match adds no control; an unavailable GitHub connection offers Integrations. No URL-pasting step is required. Existing `work pr` records remain readable for compatibility, but they are not treated as verified GitHub state. `work review` returns a Markdown review summary and a deep link for the PR description; publish it only within the user's authorized PR workflow. The deep link needs the developer's local repository/work context; it is not a hosted public preview. Legacy immutable revision/PR comparisons remain available through `fractory review`.
106
+
107
+
108
+ ## Review intentions against implementation
109
+
110
+ The blue worktree view has a **Plan** section grouped by block. Select an intention, choose **Link implementation**, then pick its actual block or connection directly on the map. Confirm **Done**, or **Drop** an intention while keeping its original request. **Reopen** puts it back in the active plan. A completed sketch gives way to the linked real block; pending proposed connections follow that explicit link. Unfinished nested sketches retain their containing block.
111
+
112
+ **Done** records a confirmation and a fingerprint of the request, current mapped source and attached files. It is not a test pass or proof of behavior. A stale source reference must be regenerated before confirmation. Later changes to that request or implementation become **Needs recheck**; changes outside the linked source files do not invalidate it. Resolving a comment thread only closes the discussion. It does not mark an intention implemented.
113
+
114
+ ```sh
115
+ fractory work show WORK_ID
116
+ fractory work intent WORK_ID --proposal PROPOSAL_ID --status planned --implementation BLOCK_OR_CONNECTION_ID --revision REVISION
117
+ fractory work intent WORK_ID --proposal PROPOSAL_ID --status done --revision REVISION
118
+ fractory work intent WORK_ID --proposal PROPOSAL_ID --status dropped --revision REVISION
119
+ fractory work review WORK_ID
120
+ ```
121
+
122
+ Use the latest revision returned by each command. `work show`, `work handoff` and `work review` expose the same current states. Continue planned items and those needing recheck; keep done and dropped decisions as records. Existing local checks remain advisory; trusted CI and protected-branch enforcement are separate.
123
+
124
+
125
+ ## Canvas selection and drawing
126
+
127
+ Cmd/Ctrl-click selects a block and its descendants. Cmd/Ctrl-A selects the inside blocks at the current map level; outside connections are not selected. Text fields keep normal Select All behavior. The selected enclosure and its included children have blue rings. Cmd/Ctrl-click an included child to exclude its subtree, or select inside that exclusion to reinclude a smaller part. On Main, Start worktree keeps these rules. In a worktree, Update worktree selection saves staged scope changes; the context menu can also add or exclude a block directly.
128
+
129
+ Work plans store positive `scope` IDs and optional `excluded` IDs. The nearest ancestor rule wins. Preserve both through CLI plan updates; `work handoff` and `work check` use the same rules. A parent may remain in scope while a child is explicitly excluded.
130
+
131
+ The blue Block tool previews placement before a click. Name the block directly on the card. Connect by dragging blue handles or clicking a source and destination; name the connection on its wire. Enter or blur saves the name; Escape cancels a new unnamed sketch. Plan saves are ordered and show failures rather than silently discarding fast actions.
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env node
2
+ import "../../dist/bin.js";
@@ -0,0 +1 @@
1
+ {"version":"0.1.24"}