@starlove/orbit 1.3.5 → 1.4.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 (129) hide show
  1. package/Dockerfile +2 -1
  2. package/README.md +10 -9
  3. package/SKILL-ORBIT.md +41 -17
  4. package/dist/full/fonts/Chakra_Petch/ChakraPetch-Bold.ttf +0 -0
  5. package/dist/full/fonts/Chakra_Petch/ChakraPetch-BoldItalic.ttf +0 -0
  6. package/dist/full/fonts/Chakra_Petch/ChakraPetch-Italic.ttf +0 -0
  7. package/dist/full/fonts/Chakra_Petch/ChakraPetch-Light.ttf +0 -0
  8. package/dist/full/fonts/Chakra_Petch/ChakraPetch-LightItalic.ttf +0 -0
  9. package/dist/full/fonts/Chakra_Petch/ChakraPetch-Medium.ttf +0 -0
  10. package/dist/full/fonts/Chakra_Petch/ChakraPetch-MediumItalic.ttf +0 -0
  11. package/dist/full/fonts/Chakra_Petch/ChakraPetch-Regular.ttf +0 -0
  12. package/dist/full/fonts/Chakra_Petch/ChakraPetch-SemiBold.ttf +0 -0
  13. package/dist/full/fonts/Chakra_Petch/ChakraPetch-SemiBoldItalic.ttf +0 -0
  14. package/dist/full/fonts/Chakra_Petch/OFL.txt +93 -0
  15. package/dist/full/fonts/Inter/Inter-Italic-VariableFont_opsz,wght.ttf +0 -0
  16. package/dist/full/fonts/Inter/Inter-VariableFont_opsz,wght.ttf +0 -0
  17. package/dist/full/fonts/Inter/OFL.txt +93 -0
  18. package/dist/full/fonts/Inter/README.txt +118 -0
  19. package/dist/full/fonts/JetBrains_Mono/JetBrainsMono-Italic-VariableFont_wght.ttf +0 -0
  20. package/dist/full/fonts/JetBrains_Mono/JetBrainsMono-VariableFont_wght.ttf +0 -0
  21. package/dist/full/fonts/JetBrains_Mono/OFL.txt +93 -0
  22. package/dist/full/fonts/JetBrains_Mono/README.txt +79 -0
  23. package/dist/full/fonts/OpenRing-Regular.ttf +0 -0
  24. package/dist/full/fonts/Open_Sans/OFL.txt +93 -0
  25. package/dist/full/fonts/Open_Sans/OpenSans-Italic-VariableFont_wdth,wght.ttf +0 -0
  26. package/dist/full/fonts/Open_Sans/OpenSans-VariableFont_wdth,wght.ttf +0 -0
  27. package/dist/full/fonts/Open_Sans/README.txt +100 -0
  28. package/dist/full/fonts/Orbitron/OFL.txt +93 -0
  29. package/dist/full/fonts/Orbitron/Orbitron-VariableFont_wght.ttf +0 -0
  30. package/dist/full/fonts/Orbitron/README.txt +68 -0
  31. package/dist/full/fonts/Rajdhani/OFL.txt +93 -0
  32. package/dist/full/fonts/Rajdhani/Rajdhani-Bold.ttf +0 -0
  33. package/dist/full/fonts/Rajdhani/Rajdhani-Light.ttf +0 -0
  34. package/dist/full/fonts/Rajdhani/Rajdhani-Medium.ttf +0 -0
  35. package/dist/full/fonts/Rajdhani/Rajdhani-Regular.ttf +0 -0
  36. package/dist/full/fonts/Rajdhani/Rajdhani-SemiBold.ttf +0 -0
  37. package/dist/full/fonts/runescape-uf.ttf +0 -0
  38. package/dist/full/index.html +135 -25
  39. package/dist/full/js/app.62905fcb.js +952 -0
  40. package/dist/full/js/app.62905fcb.js.map +7 -0
  41. package/dist/full/styles.4e60d824.css +1 -0
  42. package/dist/full/version.json +2 -2
  43. package/docs/AGENT_PROTOCOL.md +20 -13
  44. package/docs/ORBIT_DISPATCH.md +73 -38
  45. package/docs/UPDATING.md +114 -0
  46. package/package.json +5 -7
  47. package/public/fonts/Chakra_Petch/ChakraPetch-Bold.ttf +0 -0
  48. package/public/fonts/Chakra_Petch/ChakraPetch-BoldItalic.ttf +0 -0
  49. package/public/fonts/Chakra_Petch/ChakraPetch-Italic.ttf +0 -0
  50. package/public/fonts/Chakra_Petch/ChakraPetch-Light.ttf +0 -0
  51. package/public/fonts/Chakra_Petch/ChakraPetch-LightItalic.ttf +0 -0
  52. package/public/fonts/Chakra_Petch/ChakraPetch-Medium.ttf +0 -0
  53. package/public/fonts/Chakra_Petch/ChakraPetch-MediumItalic.ttf +0 -0
  54. package/public/fonts/Chakra_Petch/ChakraPetch-Regular.ttf +0 -0
  55. package/public/fonts/Chakra_Petch/ChakraPetch-SemiBold.ttf +0 -0
  56. package/public/fonts/Chakra_Petch/ChakraPetch-SemiBoldItalic.ttf +0 -0
  57. package/public/fonts/Chakra_Petch/OFL.txt +93 -0
  58. package/public/fonts/Inter/Inter-Italic-VariableFont_opsz,wght.ttf +0 -0
  59. package/public/fonts/Inter/Inter-VariableFont_opsz,wght.ttf +0 -0
  60. package/public/fonts/Inter/OFL.txt +93 -0
  61. package/public/fonts/Inter/README.txt +118 -0
  62. package/public/fonts/JetBrains_Mono/JetBrainsMono-Italic-VariableFont_wght.ttf +0 -0
  63. package/public/fonts/JetBrains_Mono/JetBrainsMono-VariableFont_wght.ttf +0 -0
  64. package/public/fonts/JetBrains_Mono/OFL.txt +93 -0
  65. package/public/fonts/JetBrains_Mono/README.txt +79 -0
  66. package/public/fonts/OpenRing-Regular.ttf +0 -0
  67. package/public/fonts/Open_Sans/OFL.txt +93 -0
  68. package/public/fonts/Open_Sans/OpenSans-Italic-VariableFont_wdth,wght.ttf +0 -0
  69. package/public/fonts/Open_Sans/OpenSans-VariableFont_wdth,wght.ttf +0 -0
  70. package/public/fonts/Open_Sans/README.txt +100 -0
  71. package/public/fonts/Orbitron/OFL.txt +93 -0
  72. package/public/fonts/Orbitron/Orbitron-VariableFont_wght.ttf +0 -0
  73. package/public/fonts/Orbitron/README.txt +68 -0
  74. package/public/fonts/Rajdhani/OFL.txt +93 -0
  75. package/public/fonts/Rajdhani/Rajdhani-Bold.ttf +0 -0
  76. package/public/fonts/Rajdhani/Rajdhani-Light.ttf +0 -0
  77. package/public/fonts/Rajdhani/Rajdhani-Medium.ttf +0 -0
  78. package/public/fonts/Rajdhani/Rajdhani-Regular.ttf +0 -0
  79. package/public/fonts/Rajdhani/Rajdhani-SemiBold.ttf +0 -0
  80. package/public/fonts/runescape-uf.ttf +0 -0
  81. package/public/index.html +133 -23
  82. package/public/js/artifact-drawer.js +79 -0
  83. package/public/js/board-export.js +161 -0
  84. package/public/js/board-menu.js +219 -17
  85. package/public/js/card-actions.js +1 -1
  86. package/public/js/create-card.js +60 -23
  87. package/public/js/drawer.js +164 -4
  88. package/public/js/font-preference.js +229 -0
  89. package/public/js/format.js +0 -10
  90. package/public/js/icons.js +16 -0
  91. package/public/js/local-backend.js +31 -4
  92. package/public/js/main.js +7 -1
  93. package/public/js/modal.js +3 -1
  94. package/public/js/panel.js +58 -0
  95. package/public/js/settings-tabs.js +1 -1
  96. package/public/js/settings.js +606 -275
  97. package/public/js/sse.js +3 -0
  98. package/public/js/state.js +1 -1
  99. package/public/js/text-editing.js +128 -0
  100. package/public/js/ticket-detail.js +377 -148
  101. package/public/js/ticket-typeahead.js +49 -0
  102. package/public/js/toast.js +19 -4
  103. package/public/js/topbar-notes.js +3 -3
  104. package/public/js/typeahead.js +206 -0
  105. package/public/js/update-check.js +58 -0
  106. package/public/styles.css +5447 -3572
  107. package/src/cli/orbit.js +9 -5
  108. package/src/core/agent.js +12 -4
  109. package/src/core/agents-md.js +3 -3
  110. package/src/core/artifacts.js +149 -0
  111. package/src/core/board.js +3 -2
  112. package/src/core/boards.js +0 -1
  113. package/src/core/css-bundle.js +1 -0
  114. package/src/core/db.js +6 -0
  115. package/src/core/dispatch.js +344 -34
  116. package/src/core/http.js +9 -2
  117. package/src/core/paths.js +26 -2
  118. package/src/core/router.js +33 -0
  119. package/src/core/search.js +3 -2
  120. package/src/core/snapshots.js +10 -5
  121. package/src/core/tickets.js +34 -3
  122. package/src/core/util.js +3 -2
  123. package/src/core/version-check.js +154 -0
  124. package/src/mcp/orbit-client.js +18 -2
  125. package/src/mcp-server.js +19 -14
  126. package/src/server.js +28 -3
  127. package/dist/full/js/app.4ae80764.js +0 -742
  128. package/dist/full/js/app.4ae80764.js.map +0 -7
  129. package/dist/full/styles.b9e0c130.css +0 -1
@@ -95,13 +95,13 @@ GET /api/tickets/:id/context?depth=1
95
95
  Returns:
96
96
 
97
97
  - Ticket, board identity, state, labels.
98
- - Dedicated implementation fields: `ai_plan`, `implementation_summary`, and `implementation_updates`.
98
+ - Human-visible card fields: terse AI Plan (`ai_plan`), terse Work Summary (`implementation_summary`), and Revisions (`implementation_updates`); full handoffs/reports live in linked markdown artifact paths. Board Journal decisions/lessons carry the most important code/pattern/project context loaded for every agent on the board.
99
99
  - Parent epic/story ticket when present.
100
100
  - Child feature cards when the ticket is an epic/story.
101
101
  - Related tickets.
102
102
  - Blockers and blocking tickets.
103
103
 
104
- Project manual/journal (`agent_instructions`, `project_notes`, and board entries) and ticket comments are intentionally omitted from this default agent context. Fetch project context and comments explicitly when needed:
104
+ Project manual/journal (`agent_instructions` and board entries) and ticket comments are intentionally omitted from this default agent context. Human-only `project_notes` are not part of agent context surfaces. Fetch project context and comments explicitly when needed:
105
105
 
106
106
  ```http
107
107
  GET /api/boards/:board_id/context?include_struck=false
@@ -192,7 +192,7 @@ Searches ticket titles, descriptions, and comments.
192
192
  GET /api/boards/:board_id/context?include_struck=false
193
193
  ```
194
194
 
195
- Returns the same shape as MCP `board_context`: board metadata (`agent_instructions`, `project_notes`, repository paths, default branch), `entries` (journal / decisions / lessons), and `deployment` paths. Use `include_struck=true` to include struck journal rows (default off).
195
+ Returns the same shape as MCP `board_context`: agent-safe board metadata (`agent_instructions`, repository paths, default branch), `entries` (journal / decisions / lessons), and `deployment` paths. Human-only `project_notes` are intentionally excluded. Use `include_struck=true` to include struck journal rows (default off).
196
196
 
197
197
  MCP: `board_context` with optional `board_id` / `board_slug` / `board` and optional `include_struck`.
198
198
 
@@ -207,8 +207,7 @@ Content-Type: application/json
207
207
  "repo_url": "https://github.com/you/repo",
208
208
  "system_path": "C:/path/to/repo",
209
209
  "default_branch": "main",
210
- "project_notes": "Personal reminders (optional).",
211
- "agent_instructions": "Why this repo exists, capabilities, stack, constraints, and how agents should operate..."
210
+ "agent_instructions": "How agents should work here..."
212
211
  }
213
212
  ```
214
213
 
@@ -281,24 +280,32 @@ Content-Type: application/json
281
280
 
282
281
  Comments are for discussion and event breadcrumbs. Use the dedicated fields below for durable implementation records.
283
282
 
284
- ### Update AI Plan / Implementation Fields
283
+ ### Ticket Field Contract
285
284
 
286
285
  ```http
287
286
  PATCH /api/tickets/:id
288
287
  Content-Type: application/json
289
288
 
290
289
  {
291
- "ai_plan": "The current plan...",
292
- "implementation_summary": "What shipped...",
293
- "implementation_updates": "Progress notes, mistakes to avoid, discoveries..."
290
+ "ai_plan": "Next: implement the sync queue, add conflict tests, verify with pnpm test.",
291
+ "plan_artifact_path": ".orbit/dispatch-runs/.../handoff.md",
292
+ "implementation_summary": "Shipped sync queue + conflict tests. pnpm test passed. Risk: mobile offline smoke remains human-owned.",
293
+ "implementation_artifact_path": ".orbit/dispatch-runs/.../report.md",
294
+ "implementation_updates": "Revision: narrowed conflict retry to failed operations only."
294
295
  }
295
296
  ```
296
297
 
297
298
  Field intent:
298
299
 
299
- - `ai_plan`: The current plan. For epics, this should describe the high-level vision and feature breakdown. For feature/task/bug cards, this should describe the concrete implementation approach.
300
- - `implementation_summary`: The final concise summary of what changed, usually written when the card moves to review or done.
301
- - `implementation_updates`: Chronological notes, mistakes, discoveries, and "avoid this next time" material. Later this can feed a separate insights system.
300
+ - `ai_plan`: existing AI Plan field. Store a terse visible plan summary for humans. Use `plan_artifact_path` for full markdown/text handoffs or plan docs.
301
+ - `plan_artifact_path`: human-editable local/repo-relative or hosted-readable markdown/text path, for example `docs/plan.md` or `./docs/plan.md`. The UI resolves it when opening the artifact; if it cannot resolve, the human can edit the path.
302
+ - `implementation_summary`: existing Work Summary field. Store a terse visible result summary for humans. Use `implementation_artifact_path` for full reports/evidence.
303
+ - `implementation_artifact_path`: human-editable local/repo-relative or hosted-readable markdown/text path to the full report/evidence artifact, for example `docs/report.md` or `./docs/report.md`.
304
+ - `implementation_updates`: Revisions. Use only for terse later changes/corrections after initial implementation. Leave blank for normal first completion; do not store chronology, command logs, run receipts, or durable project lessons here.
305
+ - Comments are for compact run receipts, transient breadcrumbs, and discussion.
306
+ - Board Journal entries are for durable reusable project decisions/lessons.
307
+
308
+ Direct `PATCH /api/tickets/:id` updates the fields exactly. For normal completion, prefer `/api/agent/complete`: its `summary` writes Work Summary (`implementation_summary`), `implementation_artifact_path` links the full report, and optional `updates` writes Revisions only when the run is a later correction/change.
302
309
 
303
310
  ### Archive, Restore, and Delete
304
311
 
@@ -396,7 +403,7 @@ Content-Type: application/json
396
403
  }
397
404
  ```
398
405
 
399
- Moves the ticket to `Review` by default and writes `summary` into `implementation_summary`. If `updates` is present, it is appended to `implementation_updates`.
406
+ Moves the ticket to `Review` by default and writes `summary` into Work Summary (`implementation_summary`). If `updates` is present, it is appended to Revisions (`implementation_updates`) without timestamp headings; omit `updates` for normal first completion notes.
400
407
 
401
408
  ## Ticket Writing Contract
402
409
 
@@ -1,6 +1,6 @@
1
1
  # Orbit Dispatch
2
2
 
3
- `orbit dispatch` is the local Orbit-to-Hermes handoff command. It turns a local Orbit ticket into a bounded agent run without relying on a temporary prompt file as the source of truth.
3
+ `orbit dispatch` is the Orbit-to-Hermes handoff command. It turns an Orbit ticket into a bounded agent run without relying on a temporary prompt file as the source of truth.
4
4
 
5
5
  The design intent is simple:
6
6
 
@@ -8,15 +8,38 @@ The design intent is simple:
8
8
  - Orbit remains canonical for planning, handoff, run records, and implementation notes.
9
9
  - The ticket becomes the shared communication surface between the human, orchestrator, and dispatched agent.
10
10
 
11
- ## Current remote-board contract
11
+ ## Local and remote board contract
12
12
 
13
- `orbit dispatch` is intentionally local-board only right now. It resolves boards through the local Orbit registry and mutates the local SQLite board file.
13
+ Local dispatch resolves boards through the local Orbit registry and mutates the local SQLite board file.
14
14
 
15
- Because of that, `--server-url` and `--remote` are refused before side effects. They do not silently target a hosted board.
15
+ Remote dispatch targets a hosted Orbit server through the HTTP API. It accepts either a full hosted ticket URL or an explicit server/board/ticket tuple:
16
16
 
17
- For hosted/remote boards, use remote MCP/manual orchestration or run `orbit dispatch` on the board host without `--server-url`/`--remote`.
17
+ ```bash
18
+ # Full hosted Orbit ticket URL. The board slug and ticket id are parsed from the hash route.
19
+ orbit dispatch 'http://orbit.example/#/b/my-app/t/<ticket-id>' --profile nova --worktree
20
+
21
+ # Equivalent explicit form.
22
+ orbit dispatch \
23
+ --server-url http://orbit.example \
24
+ --board my-app \
25
+ --ticket <ticket-id-or-number> \
26
+ --profile nova \
27
+ --worktree
28
+ ```
29
+
30
+ Remote dispatch uses hosted Orbit API state for ticket reads, blockers, AI Plan/plan artifact updates, run-record comments, and lane moves. It still uses the local `--cwd` repo as the code/worktree root, because hosted board paths may belong to another machine.
31
+
32
+ Safe preview forms work in remote mode too:
18
33
 
19
- ## Basic use
34
+ ```bash
35
+ # Reads hosted board/ticket/blocker state, then exits with no writes.
36
+ orbit dispatch 'http://orbit.example/#/b/my-app/t/<ticket-id>' --profile nova --dry-run
37
+
38
+ # Writes handoff/run record/worktree and comments the hosted ticket, but does not spawn Hermes or move the card.
39
+ orbit dispatch 'http://orbit.example/#/b/my-app/t/<ticket-id>' --profile nova --worktree --no-spawn
40
+ ```
41
+
42
+ ## Basic local use
20
43
 
21
44
  From the code repository you are working in, target the local Orbit board explicitly:
22
45
 
@@ -53,12 +76,12 @@ orbit dispatch --board my-app --ticket 12 --profile agent --worktree \
53
76
 
54
77
  ## Preflight order
55
78
 
56
- Before any filesystem writes, worktree creation, ticket mutation, or agent spawn, dispatch now:
79
+ Before filesystem writes, worktree creation, ticket mutation, or agent spawn, dispatch now:
57
80
 
58
- 1. Refuses `--server-url` / `--remote`.
59
- 2. Resolves the local board from `--board` or from `--cwd` / the current repo.
60
- 3. Resolves the ticket from `--ticket` by number or id.
61
- 4. Refuses archived tickets.
81
+ 1. Parses local vs remote target (`--server-url`, `--remote`, or hosted ticket URL select remote mode).
82
+ 2. Resolves the board from `--board`, hosted URL, or local repo context.
83
+ 3. Resolves the ticket from `--ticket` by number/id or from the hosted URL.
84
+ 4. Refuses archived/missing tickets.
62
85
  5. Refuses blocked tickets unless `--force` is passed.
63
86
  6. Rejects missing or flag-looking `--verify-command` values during CLI argument parsing.
64
87
  7. For spawn mode, checks that the Hermes binary exists and the requested profile is plausible.
@@ -71,27 +94,27 @@ Only after those checks does dispatch create run artifacts/worktrees, write the
71
94
  In normal spawn mode:
72
95
 
73
96
  1. Builds a run id such as `orbit-12-agent-abc123def0`.
74
- 2. Creates `.orbit/dispatch-runs/<run-id>/` for run metadata and policy wrappers.
75
- 3. Creates and preserves a git worktree/branch when `--worktree` is used.
97
+ 2. Creates a run directory for run metadata and policy wrappers. Local board mode uses `<DATA_DIR>/dispatch-runs/<board>/<run-id>/`; remote mode uses `<repo>/.orbit/dispatch-runs/<run-id>/` so the handoff stays with the source checkout.
98
+ 3. Creates and preserves a git worktree/branch when `--worktree` is used. Remote mode defaults to `<repo-parent>/.worktrees/<repo-name>/<run-id>/`.
76
99
  4. Generates a full agent handoff.
77
100
  5. Writes an initial durable `run-record.json` with status `prepared` before ticket mutation or agent spawn.
78
- 6. Writes the canonical handoff copy to the ticket's **AI Written-Plan** (`ai_plan`) field.
101
+ 6. Writes the canonical handoff as a linked markdown artifact and stores a terse plan summary in AI Plan.
79
102
  7. Moves the ticket to **In Progress**.
80
103
  8. Starts Hermes.
81
104
  9. Updates `run-record.json` to status `launched` with the child process id.
82
105
  10. Comments a run record back onto the ticket.
83
106
 
84
- In `--no-spawn` mode, dispatch writes the handoff, initial `run-record.json`, and run-record comment but leaves the ticket in its current lane.
107
+ In `--no-spawn` mode, dispatch writes the handoff artifact, initial `run-record.json`, and compact run-record comment but leaves the ticket in its current lane.
85
108
 
86
- The run record includes profile, policy, ticket, branch, worktree, base commit, policy-bin path, child process id, command, declared verification commands, mode, and a `run-record.json` path. This makes the card the visible cockpit for the run while preserving a machine-readable artifact for later review/repair automation.
109
+ The run record includes profile, policy, ticket, branch, worktree, base commit, policy-bin path, child process id, command, declared verification commands, mode, transport (`local` or `remote`), and a `run-record.json` path. This makes the card the visible cockpit for the run while preserving a machine-readable artifact for later review/repair automation.
87
110
 
88
111
  ## Structured run record
89
112
 
90
- Every non-dry-run dispatch writes `<DATA_DIR>/dispatch-runs/<board>/<run-id>/run-record.json` with schema `orbit.dispatch.run.v1`.
113
+ Every non-dry-run dispatch writes `run-record.json` with schema `orbit.dispatch.run.v1`.
91
114
 
92
115
  The JSON record currently captures:
93
116
 
94
- - run id, board id/slug, ticket id/number, profile, policy, mode, and status (`prepared` for `--no-spawn`, `launched` for spawned runs)
117
+ - run id, board id/slug, ticket id/number, profile, policy, transport, mode, and status (`prepared` for `--no-spawn`, `launched` for spawned runs)
95
118
  - prompt/handoff path, repo root, worktree, branch, and base commit
96
119
  - process id when a Hermes child was spawned
97
120
  - declared verification commands
@@ -133,17 +156,18 @@ board_get_review_verdict
133
156
 
134
157
  Comments may mirror verdict summaries for human scanning, but comments are not the source of truth for review automation. Later repair and re-review tooling should read these records directly.
135
158
 
136
- ## The AI Written-Plan handoff
159
+ ## The linked markdown handoff
137
160
 
138
- Dispatch stores the generated handoff in the ticket's AI Written-Plan field. It includes:
161
+ Dispatch stores the generated handoff as a linked markdown artifact and keeps only a terse AI Plan summary visible on the ticket. The artifact includes:
139
162
 
140
163
  - mission and ticket metadata
141
164
  - repository root, worktree, branch, and run id
142
165
  - required reading order: `AGENTS.md`, `SKILL-ORBIT.md`, then the handoff
143
166
  - ticket description
144
- - implementation fields (`ai_plan`, `implementation_summary`, `implementation_updates`)
145
- - board-level agent instructions and notes
146
- - board journal lessons/decisions
167
+ - terse AI Plan / Work Summary text, Revisions, and any linked artifact paths
168
+ - board-level agent instructions
169
+ - board Journal lessons/decisions when available
170
+ - recent remote comments when remote dispatch uses the lean dispatch packet
147
171
  - parent/child ticket context
148
172
  - unresolved blockers
149
173
  - scope boundaries
@@ -157,22 +181,29 @@ Board journal entries are framed as project constraints and lessons, not persona
157
181
 
158
182
  ## Preserved worktrees
159
183
 
160
- Use `--worktree` when the agent will edit code. Dispatch creates a normal git worktree under `.worktrees/` by default and gives the agent that directory as its working directory.
184
+ Use `--worktree` when the agent will edit code. Dispatch creates a normal git worktree and gives the agent that directory as its working directory.
161
185
 
162
186
  This solves the ephemeral-agent problem: humans can test the branch/worktree before cleanup.
163
187
 
164
- Default shape:
188
+ Default local shape:
165
189
 
166
190
  ```text
167
- .worktrees/<board>-<ticket>-<profile>-<shortid>
191
+ <repo>/.worktrees/<board>-<ticket>-<profile>-<shortid>
168
192
  orbit/<board>-<ticket>-<profile>-<shortid>
169
193
  ```
170
194
 
195
+ Default remote shape:
196
+
197
+ ```text
198
+ <repo-parent>/.worktrees/<repo-name>/<run-id>
199
+ orbit/<ticket>-<profile>-remote-<shortid>
200
+ ```
201
+
171
202
  `.worktrees/` is ignored by git.
172
203
 
173
204
  ## Safe autonomous policy
174
205
 
175
- The default policy prepends `.orbit/dispatch-runs/<run-id>/policy-bin` to the child agent's `PATH`. That directory contains wrappers for commands that should be restricted during an autonomous run.
206
+ The default policy prepends the run directory’s `policy-bin` to the child agent's `PATH`. That directory contains wrappers for commands that should be restricted during an autonomous run.
176
207
 
177
208
  Allowed:
178
209
 
@@ -201,10 +232,11 @@ The dispatched agent should:
201
232
 
202
233
  1. Run relevant tests and focused manual/API checks.
203
234
  2. Commit locally on the dispatch branch.
204
- 3. Update **AI Implementation Summary** (`implementation_summary`) with what changed, commit SHA, branch/worktree, verification, and manual checks still needed.
205
- 4. Add **Implementation Updates/Lessons** (`implementation_updates`) for pitfalls, remediation, and reusable guidance.
206
- 5. Add a completion comment/run record.
207
- 6. Move the card to **Review**, not Done, unless the human explicitly asked for auto-completion.
235
+ 3. Put a terse human-readable result in **Work Summary** (`implementation_summary`).
236
+ 4. If full detail matters, write a markdown report artifact and link it with `implementation_artifact_path`.
237
+ 5. Leave Revisions (`implementation_updates`) blank unless this is a later change/correction after initial implementation; promote the most important code/pattern/project lessons and decisions to board Journal entries.
238
+ 6. Add a compact completion comment/run receipt.
239
+ 7. Move the card to **Review**, not Done, unless the human explicitly asked for auto-completion.
208
240
 
209
241
  ## Installing / enabling the command
210
242
 
@@ -213,7 +245,7 @@ For source installs:
213
245
  ```bash
214
246
  cd /path/to/ss-orbit
215
247
  pnpm install
216
- pnpm run build:full
248
+ pnpm run build:bundle
217
249
  pnpm link --global
218
250
  ```
219
251
 
@@ -233,13 +265,16 @@ orbit --version
233
265
 
234
266
  ## Operator notes for orchestrators
235
267
 
236
- - Prefer `orbit dispatch` over writing a temporary handoff prompt file when targeting a local board.
268
+ - Prefer `orbit dispatch` over writing a temporary handoff prompt file when targeting an Orbit ticket.
269
+ - Use a full hosted Orbit ticket URL for the fastest remote path; dispatch will parse the server, board slug, and ticket id.
270
+ - Use `--cwd` to point remote dispatch at the local code checkout when the hosted board records another machine’s repo path.
237
271
  - Use `--dry-run` when you want proof of what would happen without any side effects.
238
272
  - Use `--no-spawn` when you want to inspect the generated handoff/worktree/comment before starting an agent.
239
273
  - Use `--worktree` for code edits so the human can test before cleanup.
240
- - Treat the ticket fields as durable surfaces:
241
- - AI Written-Plan: generated handoff
242
- - AI Implementation Summary: final summary of completed work
243
- - Implementation Updates/Lessons: pitfalls, remediation, future-agent guidance
244
- - Comments: run records and transient breadcrumbs
274
+ - Treat the ticket fields as human-visible surfaces:
275
+ - AI Plan: terse visible plan summary; full handoff/plan doc lives in human-editable `plan_artifact_path`
276
+ - Work Summary: terse visible result summary; full report/evidence doc lives in human-editable `implementation_artifact_path`
277
+ - Revisions: terse later corrections/changes after initial implementation only
278
+ - Comments: compact run receipts and transient breadcrumbs
279
+ - Board Journal: durable reusable project lessons/decisions
245
280
  - Do not push, deploy, or open PRs from the dispatched agent unless the human explicitly asked for that run to do so.
@@ -0,0 +1,114 @@
1
+ # Updating Orbit
2
+
3
+ Orbit checks GitHub for a newer version and surfaces it in the app:
4
+
5
+ - a purple dot on the **Settings** button in the topbar,
6
+ - a one-time toast on load (**“Orbit vX.Y.Z is available →”**), and
7
+ - a **Version & Updates** card at the top of **Settings → Data** with the
8
+ current version, a **Check now** button, a **Back up all boards** button, and
9
+ the exact commands for your deployment.
10
+
11
+ The check reads the `version` field of `package.json` on the project's default
12
+ branch. Your board data lives in `DATA_DIR` (default `~/.orbit`, `/data` in
13
+ Docker) — **outside** the app folder — so updating never touches it. Even so,
14
+ the card nudges you to **back up all boards** to a ZIP first.
15
+
16
+ ---
17
+
18
+ ## Before you update: back up
19
+
20
+ Settings → Data → **Version & Updates → Back up all boards**, or the Board chip
21
+ → **Export → Export All**. Both download a single ZIP of every board's
22
+ `.orbit.json` snapshot.
23
+
24
+ ---
25
+
26
+ ## Update flows
27
+
28
+ ### Local machine or your own server (git checkout)
29
+
30
+ ```sh
31
+ git pull
32
+ pnpm install
33
+ pnpm run build:bundle # rebuild the production bundle dist/full
34
+ # then restart Orbit (re-run `orbit serve` / `pnpm dev`, or your service)
35
+ ```
36
+
37
+ The rebuild matters: when `dist/full` exists, Orbit serves it instead of raw
38
+ `public/` sources, so a `git pull` alone won't show new UI.
39
+
40
+ ### Docker
41
+
42
+ No image is published to a registry yet, so update by rebuilding from source:
43
+
44
+ ```sh
45
+ git pull
46
+ docker compose build # or: docker build -t orbit .
47
+ docker compose up -d # or restart your `docker run` container
48
+ ```
49
+
50
+ Your boards persist in the `/data` volume across the rebuild.
51
+
52
+ ### Global npm install
53
+
54
+ ```sh
55
+ npm install -g @starlove/orbit@latest
56
+ # then restart Orbit
57
+ ```
58
+
59
+ ---
60
+
61
+ ## One-click self-update (opt-in, advanced)
62
+
63
+ If you run Orbit from a git checkout **under a process supervisor that
64
+ auto-restarts it**, you can enable a **Update now** button that performs the
65
+ pull + rebuild + restart for you.
66
+
67
+ Set `ORBIT_SELF_UPDATE=1` in the server environment. The button then appears in
68
+ the Version & Updates card whenever an update is available and calls
69
+ `POST /api/update`, which runs [`scripts/update.sh`](../scripts/update.sh).
70
+ Without the flag the endpoint returns `404` and the button stays hidden.
71
+
72
+ The script pulls, reinstalls, runs `build:bundle`, writes a log to
73
+ `DATA_DIR/update.log`, then signals the server process to exit so the
74
+ supervisor restarts it on the new build. **It only works if something restarts
75
+ the process** — otherwise Orbit simply stops and you restart it yourself.
76
+
77
+ Example systemd unit (`/etc/systemd/system/orbit.service`):
78
+
79
+ ```ini
80
+ [Unit]
81
+ Description=Starscape Orbit
82
+ After=network.target
83
+
84
+ [Service]
85
+ WorkingDirectory=/home/you/apps/ss-orbit
86
+ ExecStart=/usr/bin/node src/server.js
87
+ Environment=NODE_ENV=production
88
+ Environment=ORBIT_SELF_UPDATE=1
89
+ Restart=always
90
+ RestartSec=2
91
+ User=you
92
+
93
+ [Install]
94
+ WantedBy=multi-user.target
95
+ ```
96
+
97
+ `Restart=always` is what turns the script's "exit" into a clean restart on the
98
+ updated code.
99
+
100
+ ---
101
+
102
+ ## Configuration
103
+
104
+ | Env var | Default | Purpose |
105
+ | --- | --- | --- |
106
+ | `ORBIT_UPDATE_CHECK` | on | Set `0` to disable the update check entirely. |
107
+ | `ORBIT_UPDATE_TTL` | `60` | Minutes the server caches the GitHub result. |
108
+ | `ORBIT_UPDATE_BRANCH` | `master` | Branch whose `package.json` version is read. |
109
+ | `ORBIT_GITHUB_TOKEN` | — | Optional PAT for private repos / higher rate limit. |
110
+ | `ORBIT_SELF_UPDATE` | off | Set `1` to enable the gated `POST /api/update`. |
111
+
112
+ The server fetches GitHub's contents API (not the raw CDN), so the result isn't
113
+ stale-cached upstream; freshness is governed by `ORBIT_UPDATE_TTL`, and
114
+ **Check now** bypasses it (`/api/version?refresh=1`).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@starlove/orbit",
3
- "version": "1.3.5",
3
+ "version": "1.4.0",
4
4
  "description": "Starscape Orbit — local-first, pretty, human-ai-first kanban system.",
5
5
  "license": "AGPL-3.0",
6
6
  "type": "module",
@@ -21,9 +21,6 @@
21
21
  "publishConfig": {
22
22
  "access": "public"
23
23
  },
24
- "devDependencies": {
25
- "esbuild": "^0.25.0"
26
- },
27
24
  "engines": {
28
25
  "node": ">=22.13.0"
29
26
  },
@@ -44,15 +41,16 @@
44
41
  "claude-code"
45
42
  ],
46
43
  "dependencies": {
47
- "@starlove/ui": "^3.3.0"
44
+ "@starlove/ui": "^3.3.2",
45
+ "esbuild": "^0.25.0"
48
46
  },
49
47
  "scripts": {
50
48
  "dev": "node src/server.js",
51
49
  "dev:site": "pnpm run build:preview && pnpm run build:site && node serve-site.mjs",
52
50
  "orbit": "node src/cli/orbit.js",
53
- "build": "pnpm run build:full && pnpm run build:preview && pnpm run build:site",
51
+ "build": "pnpm run build:bundle && pnpm run build:preview && pnpm run build:site",
54
52
  "build:vercel": "pnpm run build:preview && pnpm run build:site",
55
- "build:full": "node build.mjs --edition=full",
53
+ "build:bundle": "node build.mjs --edition=full",
56
54
  "build:preview": "node build.mjs --edition=preview",
57
55
  "build:site": "node build.mjs --edition=site",
58
56
  "serve:site": "node serve-site.mjs",
@@ -0,0 +1,93 @@
1
+ Copyright 2018 The Chakra Petch Project Authors (https://github.com/m4rc1e/Chakra-Petch.git)
2
+
3
+ This Font Software is licensed under the SIL Open Font License, Version 1.1.
4
+ This license is copied below, and is also available with a FAQ at:
5
+ https://openfontlicense.org
6
+
7
+
8
+ -----------------------------------------------------------
9
+ SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
10
+ -----------------------------------------------------------
11
+
12
+ PREAMBLE
13
+ The goals of the Open Font License (OFL) are to stimulate worldwide
14
+ development of collaborative font projects, to support the font creation
15
+ efforts of academic and linguistic communities, and to provide a free and
16
+ open framework in which fonts may be shared and improved in partnership
17
+ with others.
18
+
19
+ The OFL allows the licensed fonts to be used, studied, modified and
20
+ redistributed freely as long as they are not sold by themselves. The
21
+ fonts, including any derivative works, can be bundled, embedded,
22
+ redistributed and/or sold with any software provided that any reserved
23
+ names are not used by derivative works. The fonts and derivatives,
24
+ however, cannot be released under any other type of license. The
25
+ requirement for fonts to remain under this license does not apply
26
+ to any document created using the fonts or their derivatives.
27
+
28
+ DEFINITIONS
29
+ "Font Software" refers to the set of files released by the Copyright
30
+ Holder(s) under this license and clearly marked as such. This may
31
+ include source files, build scripts and documentation.
32
+
33
+ "Reserved Font Name" refers to any names specified as such after the
34
+ copyright statement(s).
35
+
36
+ "Original Version" refers to the collection of Font Software components as
37
+ distributed by the Copyright Holder(s).
38
+
39
+ "Modified Version" refers to any derivative made by adding to, deleting,
40
+ or substituting -- in part or in whole -- any of the components of the
41
+ Original Version, by changing formats or by porting the Font Software to a
42
+ new environment.
43
+
44
+ "Author" refers to any designer, engineer, programmer, technical
45
+ writer or other person who contributed to the Font Software.
46
+
47
+ PERMISSION & CONDITIONS
48
+ Permission is hereby granted, free of charge, to any person obtaining
49
+ a copy of the Font Software, to use, study, copy, merge, embed, modify,
50
+ redistribute, and sell modified and unmodified copies of the Font
51
+ Software, subject to the following conditions:
52
+
53
+ 1) Neither the Font Software nor any of its individual components,
54
+ in Original or Modified Versions, may be sold by itself.
55
+
56
+ 2) Original or Modified Versions of the Font Software may be bundled,
57
+ redistributed and/or sold with any software, provided that each copy
58
+ contains the above copyright notice and this license. These can be
59
+ included either as stand-alone text files, human-readable headers or
60
+ in the appropriate machine-readable metadata fields within text or
61
+ binary files as long as those fields can be easily viewed by the user.
62
+
63
+ 3) No Modified Version of the Font Software may use the Reserved Font
64
+ Name(s) unless explicit written permission is granted by the corresponding
65
+ Copyright Holder. This restriction only applies to the primary font name as
66
+ presented to the users.
67
+
68
+ 4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
69
+ Software shall not be used to promote, endorse or advertise any
70
+ Modified Version, except to acknowledge the contribution(s) of the
71
+ Copyright Holder(s) and the Author(s) or with their explicit written
72
+ permission.
73
+
74
+ 5) The Font Software, modified or unmodified, in part or in whole,
75
+ must be distributed entirely under this license, and must not be
76
+ distributed under any other license. The requirement for fonts to
77
+ remain under this license does not apply to any document created
78
+ using the Font Software.
79
+
80
+ TERMINATION
81
+ This license becomes null and void if any of the above conditions are
82
+ not met.
83
+
84
+ DISCLAIMER
85
+ THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
86
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
87
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
88
+ OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
89
+ COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
90
+ INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
91
+ DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
92
+ FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
93
+ OTHER DEALINGS IN THE FONT SOFTWARE.