@boxes-dev/dvb-runtime 1.0.1103 → 1.0.1105

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 (33) hide show
  1. package/dist/agent-init-guides/agent-config.md +34 -0
  2. package/dist/agent-init-guides/app.md +6 -5
  3. package/dist/agent-init-guides/flow.md +72 -12
  4. package/dist/agent-init-guides/git-ssh.md +9 -4
  5. package/dist/agent-init-guides/manifest.md +6 -0
  6. package/dist/agent-init-guides/recovery.md +22 -0
  7. package/dist/agent-init-guides/running.md +12 -0
  8. package/dist/agent-init-guides/untracked.md +2 -1
  9. package/dist/bin/dvb.mjs +1228 -1758
  10. package/dist/bin/dvbd.mjs +6 -6
  11. package/dist/product-docs/references/agent-tools.md +32 -5
  12. package/dist/product-docs/references/automations.md +18 -3
  13. package/dist/product-docs/references/cli.md +6 -4
  14. package/dist/product-docs/references/core-concepts.md +1 -1
  15. package/dist/product-docs/references/desktop-workbench.md +28 -3
  16. package/dist/product-docs/references/environment-setup-validation.md +22 -0
  17. package/dist/product-docs/references/files-git-and-review.md +32 -18
  18. package/dist/product-docs/references/fork-workflows.md +6 -3
  19. package/dist/product-docs/references/getting-started.md +2 -1
  20. package/dist/product-docs/references/index.md +2 -1
  21. package/dist/product-docs/references/linear.md +15 -0
  22. package/dist/product-docs/references/member-managed-files.md +2 -1
  23. package/dist/product-docs/references/mobile.md +63 -17
  24. package/dist/product-docs/references/onbox-agent-tools.md +224 -66
  25. package/dist/product-docs/references/ports-terminal-and-runtime.md +5 -3
  26. package/dist/product-docs/references/project-setup.md +67 -17
  27. package/dist/product-docs/references/security-and-data.md +3 -2
  28. package/dist/product-docs/references/slack.md +8 -5
  29. package/dist/product-docs/references/threads-and-agents.md +25 -8
  30. package/dist/product-docs/references/troubleshooting.md +7 -5
  31. package/dist/product-docs/references/unattended-work.md +5 -0
  32. package/dist/prompts/local-services-scan.md +3 -4
  33. package/package.json +2 -2
@@ -19,6 +19,40 @@ selection with a label comment per item, and lists what was left out.
19
19
  are restored as config and re-authenticated on the Template box after setup
20
20
  (the user completes that from the desktop app).
21
21
 
22
+ `dvb agent-init detect agent-config` lists names, selection ids, and sizes;
23
+ add `--json` for source paths and exact byte counts. Sizes include linked
24
+ support files. Use the detected individual ids, such as `claude:skill:review`
25
+ or `codex:skill:.system/writer`, to choose a subset in `agentConfig.include`.
26
+ These examples illustrate the format; use the actual ids from detection.
27
+ Remove `claude:skills` or `codex:skills` for an agent whose skills you are
28
+ selecting individually. Those whole-folder ids remain supported and will
29
+ include the entire folder if retained, regardless of individual selections.
30
+ Selected skills retain their support files; the local originals are unchanged.
31
+ Whole-folder selections in saved manifests keep their existing meaning.
32
+
33
+ Review the detected configuration and recommend what will help with this
34
+ project and the user's development workflow. Skills for testing, browser
35
+ automation, or code review can be useful even when the app itself does not
36
+ depend on them. Read relevant skill descriptions and consider the tools they
37
+ need on the Template box; neither detection nor optional status alone decides
38
+ whether something belongs in the import.
39
+
40
+ Consider size alongside usefulness. A skill collection can include supporting
41
+ tools, dependencies, browser files, and caches, including linked contents;
42
+ its upload size is not just its Markdown instructions. Inspect relevant skill
43
+ descriptions read-only. Explain any large collection's value and upload cost
44
+ so the user can decide; size alone
45
+ is not a reason to exclude useful configuration or strip required support
46
+ files out of a skill.
47
+
48
+ Propose a reasonable selection, explain notable inclusions and exclusions in
49
+ the existing grouped review, and confirm large or uncertain choices with the
50
+ user. Reuse earlier answers. Do not clear the import merely to minimize bytes.
51
+
52
+ Do not modify the user's installed skills or remove required support files
53
+ to reduce upload size. Review whole-folder selections with the user before
54
+ narrowing the import.
55
+
22
56
  Present to the user as a grouped list (per agent: MCP servers, skills,
23
57
  settings, memory) and confirm anything credential-bearing. Mention skipped
24
58
  Claude hooks during review: their commands may need scripts or tools that are
@@ -6,9 +6,10 @@ this to get the app running on the Template box and verify the setup worked.
6
6
  - `app.entrypoints`: the terminal command(s) a developer runs to work on
7
7
  the app (`npm run dev`, `just dev`, `cargo run`, ...) with a one-line
8
8
  description (what it serves, which port).
9
- - `app.services`: background services expected during development — docker
10
- compose services, workers, queues, emulators — each with the command that
11
- starts it and its HTTP port when it has one (else null).
9
+ - `app.services`: supporting processes the project expects to be running
10
+ during development — databases, docker compose services, workers, queues,
11
+ emulators — each with the command that starts it and its HTTP port when it
12
+ has one (else null).
12
13
 
13
14
  Each service `name` is a unique machine identifier and must match
14
15
  `^[A-Za-z0-9._-]+$`. Use `atlas-local`, not `mongodb (Atlas local)`. The
@@ -32,8 +33,8 @@ app:
32
33
  - command: npm run dev
33
34
  description: Vite dev server on http://localhost:5173
34
35
  services:
35
- - name: redis
36
- command: docker compose -f docker-compose.dev.yml up -d redis
36
+ - name: worker
37
+ command: npm run worker
37
38
  httpPort: null
38
39
  ```
39
40
 
@@ -10,6 +10,12 @@ Ground rules:
10
10
 
11
11
  - Investigation is **read-only**. Do not write, create, modify, delete, or
12
12
  move any project files while investigating.
13
+ - Run setup commands yourself, using your normal tool approvals. Leave to the
14
+ user only the steps that need them, such as signing in, connecting accounts,
15
+ adding a key to a Git host, setup choices, and launch approval. `dvb` stores
16
+ sign-in and setup state in the user's home folder and connects to
17
+ boxes.dev, so a sandboxed shell may block it. If a command is blocked,
18
+ explain what prevented it from running.
13
19
  - Secret **values** never go in the manifest, in chat, or in any command
14
20
  output. Reference files and variable names only.
15
21
  - The user decides. Present findings, ask when evidence is ambiguous, and get
@@ -17,6 +23,11 @@ Ground rules:
17
23
  - Keep discovery focused. Start with tracked manifests and project docs, prune
18
24
  dependency/build/vendor/generated directories, and do not open minified or
19
25
  unusually large assets just because a recursive search found them.
26
+ - Choose imports for their usefulness to this project and the user's
27
+ development workflow, considering their size. Explain large imports during
28
+ review. Reuse the user's answers and group routine choices
29
+ with your recommendations in one review instead of asking one question per
30
+ empty section.
20
31
  - You never need to keep these guides in context: re-print any of them with
21
32
  `dvb agent-init guide <topic>`, and re-orient anytime with
22
33
  `dvb agent-init status` (it always names the exact next action).
@@ -98,11 +109,21 @@ repository, every repository and top-level file inside it starts selected;
98
109
  keep only what belongs in the project in `project.repositories` and
99
110
  `project.rootEntries`.
100
111
 
112
+ The manifest and its staging folder live outside the project, in boxes.dev's
113
+ folder in the user's home directory, so setup doesn't add files to their
114
+ repositories. Editing them is part of setup, not a change to project files.
115
+ Your harness may ask the user to approve each read or edit outside the
116
+ project. Group related changes into a few edits, and avoid redundant reads
117
+ while you have the current contents. Reread the manifest when the user or
118
+ another process may have changed it.
119
+
101
120
  When the manifest uses managed GitHub access, `start` also checks whether
102
121
  boxes.dev can already use the project's GitHub repositories. If it reports a
103
- GitHub access problem, run `dvb agent-init github connect` before you
104
- investigate, so the user can finish on GitHub while you work. `check` verifies
105
- access again before launch.
122
+ GitHub access problem, follow its printed fix before you investigate, so the
123
+ user can finish on GitHub while you work. When the boxes.dev GitHub App can't
124
+ access a repository, ask the user to choose App access or SSH first (see
125
+ Phase 3), and run `dvb agent-init github connect` only if they choose App
126
+ access. `check` verifies access again before launch.
106
127
 
107
128
  Read any worktree, project-overlap, or skipped-repository explanations printed by `start`.
108
129
  Explain them to the user during review and confirm the intended project scope.
@@ -129,14 +150,21 @@ account, with high reasoning where supported.
129
150
 
130
151
  For GitHub repos, the manifest defaults to `githubAccess: managed` and keeps
131
152
  the seeded GitHub `gitSsh` rows in skip mode. If start or check says GitHub is
132
- not connected, or that the boxes.dev GitHub App can't access a repository, run
133
- `dvb agent-init github connect`, have the user finish in the browser, and then
134
- re-run check. Once GitHub is connected, that command opens GitHub and prints
135
- which account the user should choose. If an installation needs an update,
136
- follow the exact action printed by check.
137
- Set `githubAccess: ssh` and the GitHub `gitSsh` rows to setup only when the user
138
- chooses the SSH alternative. GitLab and other origins continue to use their
139
- seeded `gitSsh` entries.
153
+ not connected, run `dvb agent-init github connect`, have the user finish in the
154
+ browser, and then re-run check.
155
+
156
+ If the boxes.dev GitHub App can't access a repository, ask the user how the
157
+ project should pull and push. App access needs the App installed for the
158
+ repository's owner, and an organization owner may need to approve it. SSH uses
159
+ a key added to the user's own GitHub account. Either one covers pull and push;
160
+ automatic pull request updates and follow-ups need App access. With SSH, the
161
+ user can give the App access later for those features and keep SSH for pull
162
+ and push. For App access, run `dvb agent-init github connect`; it opens GitHub
163
+ and prints which account the user should choose. If an installation needs an
164
+ update, follow the exact action printed by check. Set `githubAccess: ssh` and
165
+ the GitHub `gitSsh` rows to setup only when the user chooses SSH, and keep the
166
+ user's choice when access changes later. GitLab and other origins continue to
167
+ use their seeded `gitSsh` entries.
140
168
 
141
169
  Separately, `dvb agent-init github cli status` shows whether boxes.dev will
142
170
  sign the `gh` command into the user's connected GitHub account on their boxes.
@@ -201,8 +229,31 @@ ask the user which one they want, record that key, and remove its marker. The
201
229
  choice applies to the Template box and all of the project's devboxes and
202
230
  cannot be changed after initialization.
203
231
 
232
+ Recommend the smallest available size that fits the actual workload. Normally
233
+ size for one coding agent and one running instance of the app, plus its
234
+ required services. Separate devboxes do not share one box's CPU or memory;
235
+ do not add their requirements together. The agent's model runs through its
236
+ connected account, so a larger model does not by itself require a larger box.
237
+
238
+ For a marketing site or a modest app, start the recommendation at 4 vCPU /
239
+ 8 GB when available. Recommend more memory for evidence such as a required
240
+ local database, browser workload, or build that exceeds that capacity; choose
241
+ more CPUs for work that can use them. Use project docs, relevant local
242
+ measurements, or known service requirements. The user's laptop size, the
243
+ number of repositories, and vague future headroom are not reasons to recommend
244
+ the largest option. Explain uncertainty rather than treating it as a need for
245
+ maximum resources, and explain a team's larger default before recommending it.
246
+
247
+ Read `dvb agent-docs billing-and-limits` for the current box-hour multipliers.
248
+ Show the relative usage cost alongside the size options and explain the
249
+ recommendation in the same review. Larger sizes will consume included
250
+ box-hours and prepaid credits faster for every awake hour, even when the
251
+ extra resources are idle; the choice also applies to future devboxes. Do not
252
+ promise an in-place resize later.
253
+
204
254
  If your harness supports parallel subagents, fan out one investigator per
205
- section (each should read its section guide first). Otherwise investigate
255
+ section (each should read its section guide first and report its findings for
256
+ you to record in the manifest). Otherwise investigate
206
257
  serially — the order above works well.
207
258
 
208
259
  Replace each `TODO(agent)` marker with real findings, or an explicit empty
@@ -217,6 +268,15 @@ databases will be dumped, how the app runs, what is excluded. Concise tables
217
268
  work well. The user can reply in chat or edit the manifest file directly —
218
269
  mention its path so they can open it.
219
270
 
271
+ Include the estimated upload size and the largest selected categories, noting
272
+ any sizes you have not measured. Follow `guide agent-config` to assess skills
273
+ and their linked contents for usefulness and size, then recommend a selection.
274
+ Explain large imports and confirm uncertain choices with the user. A multi-GB
275
+ upload for a small site deserves investigation before launch, even below the
276
+ bundle limit; useful workflow tools may still justify it. Keep local
277
+ configuration, assets, and unfinished work according to the user's choices;
278
+ do not delete local files to reduce the upload.
279
+
220
280
  For a worktree, call out missing expected configuration and any files or symlink
221
281
  targets outside it. If a needed file exists in the main checkout, offer to use
222
282
  that file through an explicit `from:` entry, obtain the configuration another
@@ -18,8 +18,10 @@ gitSsh:
18
18
  Managed access uses the user's existing boxes.dev GitHub connection for the
19
19
  Template box and future devboxes. If needed, run `dvb agent-init github
20
20
  connect`, let the user finish in the browser, and rerun `check`. When a repo
21
- is not covered by the boxes.dev GitHub App, the same command opens the
22
- GitHub page that grants access. Check prints the exact GitHub action when a
21
+ is not covered by the boxes.dev GitHub App, ask the user whether to give the
22
+ App access or use SSH. For App access, the same command opens the GitHub page
23
+ that grants access; an organization owner may need to approve it. Check
24
+ prints the exact GitHub action when a
23
25
  repo is not writable or an installation needs updated access. Do not put any returned URL, connection
24
26
  id, repository id, or token in the manifest. Managed access can push changes
25
27
  under `.github/workflows` after every affected installation accepts the shown
@@ -53,8 +55,11 @@ projects. If Cargo's built-in Git client cannot use the configured authenticatio
53
55
  set `CARGO_NET_GIT_FETCH_WITH_CLI=true` during remote setup to make Cargo use Git
54
56
  for fetching. See [Cargo's Git authentication guide](https://doc.rust-lang.org/cargo/appendix/git-authentication.html).
55
57
 
56
- Set `githubAccess: ssh` to use the key flow below for GitHub. Set `skip` to
57
- leave GitHub push/pull unconfigured. Use null only when the project has no
58
+ Set `githubAccess: ssh` to use the key flow below for GitHub. SSH pull and
59
+ push don't need the App, but automatic pull request updates and follow-ups do.
60
+ The user can give the App access later for those features without changing
61
+ Git transport.
62
+ Set `skip` to leave GitHub push/pull unconfigured. Use null only when the project has no
58
63
  standard GitHub origin. GitLab and other hosts always use `gitSsh`.
59
64
 
60
65
  `githubAccess` controls Git transport only. If `templateMaintenance.watches`
@@ -97,6 +97,12 @@ validate that key against the current server catalog. Once remote setup starts,
97
97
  the project is pinned to it; changing the manifest cannot resize an in-progress
98
98
  or initialized project.
99
99
 
100
+ Follow the workload and cost guidance in `guide flow` before recommending a
101
+ size. The seeded team default is a starting value, not evidence that this app
102
+ needs it. Explain the smallest suitable option, the reason for any larger
103
+ recommendation, and its box-hour multiplier from
104
+ `dvb agent-docs billing-and-limits` before recording the user's choice.
105
+
100
106
  `githubAccess` is one project-level Git transport choice. Keep `managed` for the
101
107
  recommended connected-GitHub HTTPS path, choose `ssh` for the existing key
102
108
  flow, choose `skip` for intentionally absent GitHub push/pull, or use null only
@@ -33,6 +33,28 @@ completed — `destroy --yes` and re-run is the honest repair.
33
33
  `dvb agent-init diagnostics` prints a redacted state dump (local + remote)
34
34
  for debugging when something looks wrong.
35
35
 
36
+ ## Restart with a smaller import or box size
37
+
38
+ Inspect `status --json` first. If setup is already complete, keep the project
39
+ and explain that changing its box size requires recreating the project;
40
+ do not apply the incomplete-setup reset to it.
41
+
42
+ For an incomplete setup, stop and await only its existing local
43
+ `dvb agent-init run` process before resetting, so it cannot keep driving the
44
+ same setup during the reset. Preserve the manifest and local project files. Explain
45
+ that `dvb agent-init destroy --yes` will remove the incomplete Template box and
46
+ setup progress, and use it only with the user's approval. An explicit request
47
+ to reset that incomplete setup supplies approval; do not ask again.
48
+
49
+ Reuse the saved manifest and earlier answers. Review global skills using
50
+ `guide agent-config`, retain the files needed to run the app and preserve
51
+ approved local work, and choose the smallest suitable box using `guide flow`.
52
+ Once an upload has started, a fresh `check` can be blocked by the frozen Git
53
+ access choice, even when only import selections changed. Use the supported
54
+ reset rather than deleting state files or editing them by hand. After reset,
55
+ edit the retained manifest, run `dvb agent-init check`, show the revised size
56
+ and cost summary, and obtain launch approval before `dvb agent-init run`.
57
+
36
58
  ## Reporting a boxes.dev bug
37
59
 
38
60
  Report a bug with `dvb report-bug --stdin` when a `dvb agent-init` command
@@ -10,6 +10,15 @@ user-facing language — and records the manifest's content hash.
10
10
  Errors are structured (`ERROR at <location>: <message> / Fix: ...`) —
11
11
  address each and re-run. `--json` gives the machine form.
12
12
 
13
+ Alongside the launch summary, explain the recommended box size and its
14
+ box-hour multiplier, plus the estimated upload size and largest included
15
+ categories. Use measured sizes where available and label estimates; `check`
16
+ does not prepare the full bundle or establish its final compressed size.
17
+ Explain substantial size surprises and the useful contents behind them, then
18
+ review alternatives with the user. A large import can be reasonable when it
19
+ supports the app or the user's workflow; neither minimizing bytes nor staying
20
+ under the 15GB limit establishes that the selection is appropriate.
21
+
13
22
  ## User approval (required)
14
23
 
15
24
  Relay the launch summary to the user verbatim or lightly formatted, and get
@@ -60,5 +69,8 @@ If the command is interrupted, nothing is lost: `dvb agent-init status`
60
69
  shows where things stand and `dvb agent-init watch` re-attaches (see
61
70
  `guide recovery`).
62
71
 
72
+ Use `run` to resume an unfinished upload; `watch` only follows remote setup
73
+ after the upload has committed and will not upload the missing data.
74
+
63
75
  If `run` fails and `dvb agent-init retry` doesn't fix it, report the failure
64
76
  with `dvb report-bug --stdin` (see `guide recovery`).
@@ -42,7 +42,8 @@ Named setup files keep their own selections. Two modes:
42
42
 
43
43
  - `mode: defaults` (recommended): include untracked files, minus
44
44
  well-known dependency/cache/build folders (node_modules, venvs, build
45
- output, caches). This matches what most users want.
45
+ output, caches) and Git worktrees inside the repository. This matches what
46
+ most users want. A worktree's branch still uploads with the Git history.
46
47
  - `mode: custom`: add include/exclude patterns. Use `base: defaults` to keep
47
48
  the normal exclusions, or `base: all` to start from all eligible files.
48
49
  Omitting `base` retains the older custom behavior: all eligible files.