arcane-cli 1.1.1 → 1.3.0

package/README.md

@@ -231,7 +231,35 @@ spell update --user     # after upgrading the CLI
 spell uninstall --user  # removes only what it wrote; an edited client file is kept and named
 ```
 
-Codex, VS Code Copilot and Claude Code each discover the user tier from their own home-directory locations (`~/.agents/skills` and `~/.claude/commands`), so no VS Code setting is needed. Claude Code runs a personal command over a project command of the same name, so in a repository that still carries its own spells `/spell-*` runs the user tier's copy. Governance stays per repository — only spell delivery moves up a level.
+Codex, VS Code Copilot and Claude Code each discover the user tier from their own home-directory locations (`~/.agents/skills` and `~/.claude/commands`), so no VS Code setting is needed. Governance stays per repository — only spell delivery moves up a level.
+
+**Agents move the same way.** Your agent roster can live once per machine too:
+
+```bash
+spell agents init --user   # ~/.arcane/agents.yaml plus one definition file per role
+spell agents sync --user   # renders ~/.copilot/agents/<name>.agent.md — VS Code agent modes
+spell agents list --user   # the roster the tier holds
+```
+
+Unlike spells, agent files are never delivered by `spell init` or `spell update`: they are rendered from your roster, whose naming strategy decides each file's name and contents, so an upgrade leaves them alone by design (ARC-047). And unlike skills, VS Code does **not** collapse two agents that share a name — a repository carrying its own `.github/agents` files adds a second entry beside the tier's rather than replacing it, so opting the repository out is what produces one set.
+
+**Then let a repository stop carrying its own copies.** `spell init` offers this when the machine already has a tier, and an existing repository opts in by setting one field:
+
+```jsonc
+// .arcane.json
+{ "spell_scope": "user" }   // absent, or "repo", means this repository carries its own spells
+```
+
+```bash
+spell update          # lists the spell files this repository no longer manages — deletes nothing
+spell update --prune  # removes the untouched ones; anything you edited is kept and named
+spell agents sync     # stops writing .github/agents here; names the leftovers and the git rm line
+spell doctor          # fails loudly if the user tier it now depends on is missing
+```
+
+This is what removes the duplication: with the repository's own copies gone, one workspace holding ten Arcane projects shows one set of `/spell-*` entries, not ten. It is also what makes the answer predictable — while both tiers own a command name, which copy a client runs is not something you can read off the docs.
+
+**Shared, team and cloud repositories should stay `repo`.** The field is committed and inherited by every clone, so opting in tells *everyone* who clones that repository to get their spells from a machine-wide install they may not have. Reverse it by setting the field back and running `spell update`, which reinstalls every spell file.
 
 ---
 

package/dist/assets/.arcane/governance/portable-bootstrap.md

@@ -52,7 +52,7 @@ Paste this entire file into any AI client (Claude web, ChatGPT, etc.) to give it
 ## Where Documents Live
 
 - **Framework-managed standards:** `.arcane/governance/`. Spells reference this single installed layer; **do not create a duplicate root `governance/` tree. Enforcement: explicitly advisory prose (ARC-023) — no check scans a repo for a duplicate root-level `governance/` directory.**
-- **Framework-managed spells:** `.arcane/spells/<id>.md` is each spell's one authored source (ARC-045). The files each AI client discovers — `.github/prompts/<id>.prompt.md` for Copilot, `.claude/commands/<id>.md` for Claude Code, `.agents/skills/<id>/SKILL.md` for Codex — are thin generated shims that point back at it; edit the canonical file, never a shim. **Enforcement: executable check (ARC-023) — `npm run check:self-host-parity` re-renders every shim from its canonical file and fails on any difference; `spell update` keeps a hand-edited shim untouched and names it rather than merging into it.** The same canonical spells can also be installed once per machine — `spell init --user` puts them at `~/.arcane/spells/<id>.md` with one Codex/Copilot skill under `~/.agents/skills/` and one Claude Code command under `~/.claude/commands/` per spell (ARC-045 decision 3); governance never moves up a tier.
+- **Framework-managed spells:** `.arcane/spells/<id>.md` is each spell's one authored source (ARC-045). The files each AI client discovers — `.github/prompts/<id>.prompt.md` for Copilot, `.claude/commands/<id>.md` for Claude Code, `.agents/skills/<id>/SKILL.md` for Codex — are thin generated shims that point back at it; edit the canonical file, never a shim. **Enforcement: executable check (ARC-023) — `npm run check:self-host-parity` re-renders every shim from its canonical file and fails on any difference; `spell update` keeps a hand-edited shim untouched and names it rather than merging into it.** The same canonical spells can also be installed once per machine — `spell init --user` puts them at `~/.arcane/spells/<id>.md` with one Codex/Copilot skill under `~/.agents/skills/` and one Claude Code command under `~/.claude/commands/` per spell (ARC-045 decision 3); governance never moves up a tier. The agent roster follows the same shape (ARC-047): `spell agents init|sync --user` keeps `agents.yaml` and the role definitions at `~/.arcane` and renders one `~/.copilot/agents/<name>.agent.md` per agent, which is where VS Code looks for machine-wide agent modes. Agent files are never installed by `spell init`/`spell update` at either tier -- they are rendered from the roster, whose naming strategy picks each file's name, which is why an upgrade never touches them. A repository may then opt out of carrying its own copies entirely with `spell_scope: "user"` in `.arcane.json` (ARC-045 decision 4) — `spell update --prune` removes what it no longer manages, keeping anything you edited, and `spell doctor` fails loudly if the tier it now depends on is missing.
 - **Project-owned orientation and continuity:** `README.md`, `project.md`, `TODO.md`, `DECISIONS.md`, `ai-context/`, and `journal/`. Arcane creates missing files once and preserves existing content.
 - **Project/domain documents:** use explicit descriptive paths such as `docs/`, `security/`, `infrastructure/`, or a configured business root. These add project context alongside framework standards.
 - **Overrides survive `arcane update`:** editing a managed `.arcane/governance/` standard no longer risks silent loss. Additive project documents were always safe; a hand-edit to a shipped standard now is too. **Enforcement: executable check (ARC-038, shipped BC-31)** — `spell update` compares each file's on-disk content against its recorded hash at install time: unchanged, it refreshes normally; edited, it fetches the exact previously-installed published version as a three-way merge base against your edit and the new vendor content, auto-merging non-overlapping changes and leaving standard conflict markers only on genuine collisions. If the prior published version can't be fetched, your edit is left untouched with a warning rather than replaced.