Skip to content

docs: document that umbel apply warms the cache (Closes #11) #26

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
vessux wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: document that umbel apply warms the cache (Closes #11) #26

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 7 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -175,7 +175,7 @@ the project-vs-bundle MCP diff.
umbel list # scope-grouped bundle table
umbel show [name] # resolved manifest + sources + MCP diff
umbel build [name] [--no-cache] # warm cache, print path
umbel apply [name] [--vanilla] # pin <project>/.umbel-bundle (--vanilla = pin "no bundle")
umbel apply [name] [--vanilla] # pin <project>/.umbel-bundle + warm cache (--vanilla = pin "no bundle")
umbel unpin # remove the pin
umbel run [name] [-- ...claude args] # launch claude (bundle if name/pin, vanilla otherwise)
umbel init # multi-step authoring wizard
Expand All @@ -186,6 +186,12 @@ umbel shim path # print the shim's absolute path
umbel skills [options] # low-level skill installer (v0 picker)
```

`apply` also **builds** the chosen bundle as a side effect: it warms the
cache and atomically updates the `by-name/<name>` symlink, then prints a
`built <path>` line beside the `pinned …` line, so a subsequent plain
`umbel run` launches without a rebuild. (`apply --vanilla` only writes the
pin — it builds nothing.)

When invoked without `[name]` on a TTY, `run` / `apply` / `show` / `build`
open a picker — **full** or **scoped**, depending on the pin:

Expand Down
9 changes: 6 additions & 3 deletions docs/bundles-spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -409,8 +409,11 @@ it only appears if `__vanilla__` is listed.
**Candidates are not pre-built.** Each builds lazily on first pick or
non-interactive resolution (the existing `building bundle 'X'…` notice).

`umbel apply <name>` writes a single-candidate bundle pin. `umbel apply --vanilla`
writes the `__vanilla__` sentinel. `umbel unpin` removes the file entirely.
`umbel apply <name>` builds the bundle — warming the cache and atomically
updating the `by-name/<name>` symlink, and printing a `built <path>` line
beside the `pinned …` line — then writes a single-candidate bundle pin.
`umbel apply --vanilla` writes the `__vanilla__` sentinel (no build).
`umbel unpin` removes the file entirely.
`umbel apply` refuses (exit 2, hint to run `umbel unpin` first) to overwrite an
existing multi-candidate pin — multi-candidate pins are hand-authored. The
bundle-name regex (`^[a-z][a-z0-9-]{1,40}$`) rejects underscores so the
Expand Down Expand Up @@ -658,7 +661,7 @@ project's own `.mcp.json` is additive rather than hidden.

```
umbel run [<name>] [--no-cache] [-- ...args] # exec claude
umbel apply [<name>] [--vanilla] # write pin (--vanilla = pin "no bundle")
umbel apply [<name>] [--vanilla] # build + write pin (--vanilla = pin "no bundle", no build)
umbel unpin # remove pin
umbel list # table
umbel show [<name>] # resolved view
Expand Down
Loading