An open source design system that's fully customizable and agent ready
TypeScript
spec(AST-081): global mode, so the CLI answers in any folder and a project's own release answers inside it (#7601)
Joeyb0a6f62348b7
diff --git a/docs/architecture/cli-surface.md b/docs/architecture/cli-surface.mdindex 11715d0b2c..0150cc3e23 100644--- a/docs/architecture/cli-surface.md+++ b/docs/architecture/cli-surface.md@@ -59,22 +59,28 @@ the commands do.## System model-A run has four stages, and each one is a place where the surface is enforced+A run has five stages, and each one is a place where the surface is enforcedrather than left to the command author.1. **Preflight.** `clients/cli/bin/astryx.mjs` gates the Node version usingonly built-ins, before importing anything that could fail on an oldruntime. The gate honours `--json` with a hand-rolled envelope carrying`ERR_NODE_VERSION`.-2. **Dispatch.** `clients/cli/index.mjs` parses with Commander, sets JSON mode+2. **Release choice.** `foundation/release/handoff.mjs` chooses the release+ that answers the folder (`spec:AST-081` FR2) before anything the project+ provides loads. When that release is not this copy, the run is handed to+ it once, with the same arguments, folder, and standard streams, and ends+ with its exit status (`spec:AST-081` FR9); a release that cannot run fails+ the run with `ERR_VERSIONS_UNAVAILABLE` before any write.+3. **Dispatch.** `clients/cli/index.mjs` parses with Commander, sets JSON modein `preAction` before any command body runs, and rejects a command thatcannot support `--json` before any side effect.-3. **Work.** The command parses its arguments and calls a function in `api/`.+4. **Work.** The command parses its arguments and calls a function in `api/`.The command is a thin wrapper: parse, call, render. The API function is theunit that is scriptable and typed, and it is the source of truth for the`type` discriminator on its own envelope. `spec:AST-042` FR1 makes this thecontract; INV20–INV22 fix where each part lives.-4. **Render.** Exactly one of two paths. In `--json` mode, `jsonOut` writes a+5. **Render.** Exactly one of two paths. In `--json` mode, `jsonOut` writes asingle envelope. Otherwise the formatters render the same values as text,from a closed set of blocks (INV23). Nothing else may write to stdout.@@ -100,14 +106,16 @@ and remains available through explicit Core package selection.condition, not a fallback. A command with nothing to do exits with a result,never a question.- **INV2 — Every `--json` emission is one valid envelope.** Success is- `{apiVersion, type, data}` plus optional `package` (INV28) and `meta`. Failure is+ `{apiVersion, type, data}` plus optional `package` (INV28) and `meta`, which+ carries `answeredBy` on every success (`spec:AST-081` FR5). Failure is`{apiVersion, error, code}` plus optional `suggestions`. There is no thirdshape, no partial write, and no raw stack trace: an uncaught throw becomes anenvelope at the bin error boundary.- **INV3 — The code is the contract; the prose is not.** `code` is stable andappend-only. Once shipped, a code's meaning never changes and the code is- never removed. The `error` string may be reworded at any time. A consumer- branches on `code`.+ never removed. The `error` string may be reworded at any time. A consumer branches on `code`.+ `ERR_PROJECT_REQUIRED` and `ERR_VERSIONS_UNAVAILABLE` carry the refusals and+ failures `spec:AST-081` FR2 and FR4 define.- **INV4 — Human output is a projection of the JSON, produced only by theformatters.** `emit` accepts a renderer-produced `Block` and nothing else, soa stray string cannot reach stdout. Output is plain ASCII: no colour, no TTY@@ -120,7 +128,9 @@ and remains available through explicit Core package selection.`<parent>-<child>.doc.mjs`.- **INV7 — Every command ships a `CommandDoc`, and the generated surfaces comefrom it.** Help text, the README command and error-code tables, and the- manifest are generated. None of them is written by hand.+ manifest are generated. None of them is written by hand. Every command and+ subcommand's `CommandDoc` declares `outsideProject`, which the manifest+ publishes (`spec:AST-081` FR4).- **INV8 — Exit codes do not depend on the output mode.** The same conditionexits the same way with and without `--json`, so a command works as a gatewithout parsing stdout.@@ -212,7 +222,12 @@ and remains available through explicit Core package selection.effect**, not part-way through the work.- **INV10 — Every write is confined.** Output paths pass `assertWithin`, whichcanonicalises symlinks and rejects a NUL byte; an escape is- `ERR_PATH_TRAVERSAL`. Bounded inputs are capped rather than trusted.+ `ERR_PATH_TRAVERSAL`. Bounded inputs are capped rather than trusted. The only+ writes outside a project or output folder are the per-user ones+ `spec:AST-081` FR7 lists: releases and records in the per-user cache, the+ settings and state files, and the computer-level skill file with its links or+ copy in the home folder. None follows a link in its place, and none replaces+ anything the CLI did not create.- **INV10a — Refusing a write outside its confined root is a compatible fix.**When a current record already confines the writes of a CLI operation (acommand or its programmatic API) to a root, a change that makes the operation@@ -246,11 +261,15 @@ and remains available through explicit Core package selection.owned by the checks that read them.- **INV12 — Human chatter never touches stdout in JSON mode.** `humanLog` and`humanWarn` are the only chatter primitives, and both are no-ops under- `--json`.+ `--json`. The run-level lines `spec:AST-081` defines, which print before or+ after a command (who answered, the fallback warning, install progress, and+ update notices), go to standard error and print nothing under `--json`.- **INV13 — Agent docs have one rendered source of truth.** Init and upgraderender configured integration `agentDocs` through the existing `Project`seam. Upgrade compares complete block bytes even when Core is unchanged and,when codemods or hooks run, writes the prepared block only after they succeed.+ The computer-level agent text that `astryx init --user` writes renders from+ the same source (`spec:AST-081` FR8).- **INV31 — Agent docs reach every agent from the project's own files.** Bydefault, init writes the agent-docs block so that every agent CLI reads atleast one copy, whether it starts at the project root or in a folder below@@ -286,7 +305,12 @@ and remains available through explicit Core package selection.project. A folder inside a settings folder belongs to a project when it,or a folder above it below the settings folder, has a `package.json`; thesettings folder itself never does. Init reports the folder it refused and- still succeeds, and removing a block there stays allowed.+ still succeeds, and removing a block there stays allowed. The+ computer-level skill file `spec:AST-081` FR8 writes+ (`~/.agents/skills/astryx/SKILL.md`, with its folder links or copy in other+ agents' skill folders) is not a project's agent docs: only+ `astryx init --user` and the global copy's background step write it, as+ INV10 and FR8 state.- Upgrade refreshes every copy where it is and moves none.- `--remove-agents` removes the block at the project root and in the workingfolder. Every file it would change resolves inside its own folder, or it@@ -299,6 +323,12 @@ and remains available through explicit Core package selection.alias or a non-semver protocol resolves like any other. A config entry keepsprecedence over the same package autolinked, and a dependency whose manifestfails to load is dropped rather than raised as the consuming project's issue.+ Integrations installed for the computer (`spec:AST-081` FR12) contribute+ only outside a project, from the packages installed beside the global copy.+ Inside a project they contribute nothing: `discover` and `doctor` load the+ manifest of each one the project does not install only to list as available+ the ones whose peer range admits the answering release and whose manifest+ loads.- **INV15 — Integration authoring writes one complete, discoverable contribution.**`integration add <kind> <name>` and its typed per-kind APIs share one receiptcontract. A dry run reports the same planned paths without writing. A real run@@ -377,8 +407,8 @@ and remains available through explicit Core package selection.function it calls. The handler parses its arguments, calls that function, andrenders the result through `jsonOut` or the formatter kit. It reads no files,loads no project, runs no discovery, and starts no subprocess or network- request; it may phrase hints with how the CLI was invoked, such as the package- manager's run prefix. Only command handlers, their `CommandDoc` files, and+ request; it may phrase hints with the command name `spec:AST-081` FR5's picker+ chooses. Only command handlers, their `CommandDoc` files, andtheir tests live in that directory. `clients/cli/commands/blog.mjs` is thereference handler.- **INV23 — The formatter kit is closed.** Text output is built only from the@@ -487,6 +517,9 @@ non-interactive guarantee.- `clients/cli/bin/astryx.mjs` — Node floor gate and the error boundary thatconverts an uncaught throw into an envelope.+- `foundation/release` — the release choice, the per-user release cache, the+ hand-off, `meta.answeredBy`, and the update check and its notices+ (`spec:AST-081`).- `clients/cli/index.mjs` — Commander wiring, JSON-mode gate, dispatch.- `clients/cli/commands/<name>.mjs` — one command: parse, call the API, render.- `clients/cli/commands/<name>.doc.mjs` — the `CommandDoc` that generates help@@ -523,6 +556,8 @@ non-interactive guarantee.function.- `spec:AST-042/DEC-2` — every command's text output uses one shared blockvocabulary.+- `spec:AST-081` — which release answers a run, the hand-off, what every+ command does outside a project, and `meta.answeredBy`.### DEC-1 — Doctor is the one command a broken configured integration fails@@ -653,29 +688,29 @@ the destination.## Verification-| Invariant | Evidence | Failure signal |-| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |-| INV1 | `clients/cli/commands/interactive-guard.test.mjs` | The subprocess hangs: `signal === 'SIGTERM'` and `status === null`. |-| INV2 | `clients/cli/commands/json-contract.test.mjs` | `--json` stdout does not parse, or parses to a shape outside the two. |-| INV3 | `foundation/response/error-codes.test.mjs` | A shipped code disappears, or an envelope carries an unregistered one. |-| INV4 | `clients/cli/formatters/index.test.mjs`, type tests | `emit` accepts a bare string, or output varies between pipe and TTY. |-| INV6 | `pnpm check:cli-structure` | A command's file or its doc is missing, or sits at the wrong path. |-| INV8 | `clients/cli/cli-exit-codes.test.mjs` | The same condition exits differently with and without `--json`. |-| INV14 | `foundation/integrations/autolink.test.mjs`, `foundation/config/project.test.mjs` | An undeclared package contributes, or configured/local precedence changes. |-| INV15 | `api/integration/add-contribution.test.mjs`, `clients/cli/commands/integration-authoring.test.mjs` | Dry-run/write paths differ, a writer clobbers bytes, or the new contribution is not discoverable. |-| INV16 | `foundation/integrations/manifest-writer.test.mjs`, `api/integration/add-contribution.test.mjs` | A writer invents package policy, replaces an author entry, or local bytes lose precedence. |-| INV17 | `api/integration/pack-check.test.mjs` | Lifecycle output, packed files, identities, or public imports diverge without failing the gate. |-| INV18 | `api/integration/validate-integration.test.mjs`, `api/theme/integration-themes.test.mjs` | Diagnostics mutate files, or a selected broken theme package is reported as merely unknown. |-| INV19 | `clients/cli/commands/integration-real-world.test.mjs` | A CLI-authored theme, nested palette, or guides fail across pack, install, list, add, and build. |-| INV20 | `pnpm check:cli-structure` checks that each subject has a `FunctionDoc`, typedefs, and a test; per-function coverage and leaf layout are checked in review | A subject or exported function lacks its `FunctionDoc`, typedefs, or tests, or an operation sits outside its subject. |-| INV21 | Review of imports under `api/**`; no mechanical check yet | A module other than a subject's adapter reads or writes files, contacts the network, starts a subprocess, loads the project, or runs discovery. |-| INV22 | Review of imports under `clients/cli/commands/**`; the docs drift harness checks each `CommandDoc` against the live command | A handler reaches the environment itself, an executable command's `CommandDoc` names no `fn`, or a non-command file sits in the directory. |-| INV23 | `clients/cli/formatters/index.test.mjs` for the kit; review of handlers; no mechanical check yet | A handler pads, aligns, or draws text itself, or a block kind is missing from the help "Output format" list. |-| INV24 | `api/integration/add-contribution.test.mjs`, `api/integration/add-theme.test.mjs`, `foundation/discovery/theme-discovery.test.mjs` | New authoring emits an untyped or non-`.doc.mjs` item, adding one item edits a shared file, or an item catalog becomes authoritative. |-| INV25 | `foundation/discovery/cli-self-docs.test.mjs`, `api/doctor/doctor.test.mjs` | A CLI doc with no namespace, a namespace no topic reads, or no section in its topic passes doctor. |-| INV28 | `test/inv28-package-provenance.test.mjs`, `clients/cli/commands/text-json-parity.test.mjs`, `cli-api-types-verify` | A result about one artifact has no envelope `package`, a listed artifact has no `package`, or text omits the package the envelope names. |-| INV29 | `api/doctor/doctor.test.mjs` (configured-integrations: not installed, no manifest, manifest throws; self-named authored package, direct and through a symlinked `node_modules` or `cwd`; provider-conflict set-aside; an astryx.config that imports but cannot load the project → failed `config` check)| A configured integration that cannot load leaves `doctor` at exit 0, or an installed-but-unnamed one fails it |-| INV31 | `foundation/agent-docs/agent-docs.test.mjs`, `foundation/agent-docs/agent-docs.path-safety.test.mjs`, `clients/cli/commands/init.behavior.test.mjs`, `api/init/remove/remove.test.mjs`, `clients/cli/commands/doctor.test.mjs` | A layout test finds the block missing from a file INV31 names or present in a file it excludes, a managed import of a block-less `AGENTS.md` passes doctor, agent docs land in the home folder or in a settings folder outside a project, or `--remove-agents` leaves a block at the project root or in the working folder. |+| Invariant | Evidence | Failure signal |+| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |+| INV1 | `clients/cli/commands/interactive-guard.test.mjs` | The subprocess hangs: `signal === 'SIGTERM'` and `status === null`. |+| INV2 | `clients/cli/commands/json-contract.test.mjs` | `--json` stdout does not parse, or parses to a shape outside the two. |+| INV3 | `foundation/response/error-codes.test.mjs` | A shipped code disappears, or an envelope carries an unregistered one. |+| INV4 | `clients/cli/formatters/index.test.mjs`, type tests | `emit` accepts a bare string, or output varies between pipe and TTY. |+| INV6 | `pnpm check:cli-structure` | A command's file or its doc is missing, or sits at the wrong path. |+| INV8 | `clients/cli/cli-exit-codes.test.mjs` | The same condition exits differently with and without `--json`. |+| INV14 | `foundation/integrations/autolink.test.mjs`, `foundation/config/project.test.mjs` | An undeclared package contributes, or configured/local precedence changes. |+| INV15 | `api/integration/add-contribution.test.mjs`, `clients/cli/commands/integration-authoring.test.mjs` | Dry-run/write paths differ, a writer clobbers bytes, or the new contribution is not discoverable. |+| INV16 | `foundation/integrations/manifest-writer.test.mjs`, `api/integration/add-contribution.test.mjs` | A writer invents package policy, replaces an author entry, or local bytes lose precedence. |+| INV17 | `api/integration/pack-check.test.mjs` | Lifecycle output, packed files, identities, or public imports diverge without failing the gate. |+| INV18 | `api/integration/validate-integration.test.mjs`, `api/theme/integration-themes.test.mjs` | Diagnostics mutate files, or a selected broken theme package is reported as merely unknown. |+| INV19 | `clients/cli/commands/integration-real-world.test.mjs` | A CLI-authored theme, nested palette, or guides fail across pack, install, list, add, and build. |+| INV20 | `pnpm check:cli-structure` checks that each subject has a `FunctionDoc`, typedefs, and a test; per-function coverage and leaf layout are checked in review | A subject or exported function lacks its `FunctionDoc`, typedefs, or tests, or an operation sits outside its subject. |+| INV21 | Review of imports under `api/**`; no mechanical check yet | A module other than a subject's adapter reads or writes files, contacts the network, starts a subprocess, loads the project, or runs discovery. |+| INV22 | Review of imports under `clients/cli/commands/**`; the docs drift harness checks each `CommandDoc` against the live command | A handler reaches the environment itself, an executable command's `CommandDoc` names no `fn`, or a non-command file sits in the directory. |+| INV23 | `clients/cli/formatters/index.test.mjs` for the kit; review of handlers; no mechanical check yet | A handler pads, aligns, or draws text itself, or a block kind is missing from the help "Output format" list. |+| INV24 | `api/integration/add-contribution.test.mjs`, `api/integration/add-theme.test.mjs`, `foundation/discovery/theme-discovery.test.mjs` | New authoring emits an untyped or non-`.doc.mjs` item, adding one item edits a shared file, or an item catalog becomes authoritative. |+| INV25 | `foundation/discovery/cli-self-docs.test.mjs`, `api/doctor/doctor.test.mjs` | A CLI doc with no namespace, a namespace no topic reads, or no section in its topic passes doctor. |+| INV28 | `test/inv28-package-provenance.test.mjs`, `clients/cli/commands/text-json-parity.test.mjs`, `cli-api-types-verify` | A result about one artifact has no envelope `package`, a listed artifact has no `package`, or text omits the package the envelope names. |+| INV29 | `api/doctor/doctor.test.mjs` (configured-integrations: not installed, no manifest, manifest throws; self-named authored package, direct and through a symlinked `node_modules` or `cwd`; provider-conflict set-aside; an astryx.config that imports but cannot load the project → failed `config` check) | A configured integration that cannot load leaves `doctor` at exit 0, or an installed-but-unnamed one fails it |+| INV31 | `foundation/agent-docs/agent-docs.test.mjs`, `foundation/agent-docs/agent-docs.path-safety.test.mjs`, `clients/cli/commands/init.behavior.test.mjs`, `api/init/remove/remove.test.mjs`, `clients/cli/commands/doctor.test.mjs` | A layout test finds the block missing from a file INV31 names or present in a file it excludes, a managed import of a block-less `AGENTS.md` passes doctor, agent docs land in the home folder or in a settings folder outside a project, or `--remove-agents` leaves a block at the project root or in the working folder. || INV32 | `test/cli-strict-guard.test.mjs` lists every command offering `--strict` and every command whose exit depends on warnings; `api/integration/check/check.test.mjs` compares a strict run with the default run | A second command offers `--strict`, a command exits 1 on a warning alone without `--strict`, or a strict run reports a finding the default run does not or outside the command's issue format. || INV33 | `foundation/discovery/prop-drift.test.mjs`, `foundation/discovery/type-text.test.mjs`, `clients/cli/commands/doctor-integration.test.mjs`, `test/core-prop-docs.test.mjs` | A removed or renamed prop or a changed union passes unreported, a missing compiler reads as a pass, or a table that leaves out `ref`, `key`, `xstyle`, `className`, `style`, `data-testid`, or an `@internal` prop draws a warning. || INV34 | `foundation/discovery/doc-types.test.mjs`, `clients/cli/commands/doctor-integration.test.mjs`, `test/core-doc-types.test.mjs` | An unknown, missing, or mistyped field passes unreported, or a missing compiler reads as a pass. |diff --git a/docs/contributing/cli-conventions.md b/docs/contributing/cli-conventions.mdindex 8a00e2c7cf..64db1c8ee0 100644--- a/docs/contributing/cli-conventions.md+++ b/docs/contributing/cli-conventions.md@@ -157,7 +157,8 @@ name, the command that lists valid values.A command is not done without its `CommandDoc` in `<name>.doc.mjs`. Fill in`summary`, `description`, `args`, `options` (each with a description),-`examples`, `exitCodes`, and `related`. Help text, the README tables, and the+`examples`, `exitCodes`, `related`, and `outsideProject`: what the command does+outside a project. Help text, the README tables, and themanifest are generated from it, so an undocumented flag is an invisible flag.Give at least one example that an agent would actually run, including a `--json`@@ -218,6 +219,8 @@ change.refused with a message, or cannot co-occur.- [ ] Any path you write passes through `assertWithin`.- [ ] The doc lists the new flag, an example, and the exit codes.+- [ ] The doc declares `outsideProject` (`same`, `refuse`, or `own`), and a test+ run outside a project matches it.- [ ] Marked as work in progress if it is not ready to be depended on.## Common review smellsdiff --git a/docs/specs/AST-047-navigable-output/spec.md b/docs/specs/AST-047-navigable-output/spec.mdindex 20fd9d8c08..0b26cf216a 100644--- a/docs/specs/AST-047-navigable-output/spec.md+++ b/docs/specs/AST-047-navigable-output/spec.md@@ -66,8 +66,9 @@ This record owns the moves a read offers and how they appear in text and JSON.smallest that answers (`spec:AST-046` FR10), with the command that reads itand the command that opens the level above it.- **FR7 — Moves are commands, and JSON carries them.** In text, each move MUST- be a whole command with the project's run prefix. In JSON, a read MUST carry- its moves as data: `links`, with `up`, `previous` and `next` where FR4 applies, and+ be a whole command that starts with the command name `spec:AST-081` FR5+ picks. In JSON, a read MUST carry its moves as data: `links`, with `up`,+ `previous` and `next` where FR4 applies, and`related` where FR5 applies to a typed doc, each an `astryx ...` command; a search hit carries `command` and`parent`. `links` MUST be present on every read but the topic list, as a fieldadded to each existing response, and the published types MUST type each move@@ -121,8 +122,9 @@ This record owns the moves a read offers and how they appear in text and JSON.### Platform support-The moves are plain commands with the prefix of the project's package manager,-so they run in any shell the CLI runs in. JSON carries them without the prefix.+The moves are plain commands that start with the command name `spec:AST-081`+FR5 picks, so they run in any shell the CLI runs in. JSON carries them without+that name.## Current-state impactdiff --git a/docs/specs/AST-048-build-recommendation/spec.md b/docs/specs/AST-048-build-recommendation/spec.mdindex e021164449..57afcf3700 100644--- a/docs/specs/AST-048-build-recommendation/spec.md+++ b/docs/specs/AST-048-build-recommendation/spec.md@@ -204,8 +204,9 @@ own ranking and output, and template owners own what each template is.### Platform support- Supported floor: every shell and package manager the CLI already supports.- Commands are printed with the project's run prefix in text and without it in- JSON, as the CLI does for every command it prints; the install command+ Commands are printed in text with the command name `spec:AST-081` FR5+ picks, and without it in JSON, as the CLI does for every command it prints;+ the install command(FR17) is the package manager's own and reads the same in both. The commonshells an install command runs in as printed (FR18) are sh-compatible shellssuch as bash and zsh, fish, PowerShell (Windows PowerShell 5.1 and PowerShelldiff --git a/docs/specs/AST-051-discover-integration-manager/spec.md b/docs/specs/AST-051-discover-integration-manager/spec.mdindex 101286c1bf..178ef757c1 100644--- a/docs/specs/AST-051-discover-integration-manager/spec.md+++ b/docs/specs/AST-051-discover-integration-manager/spec.md@@ -96,18 +96,20 @@ discover sources follow it except where this record says otherwise.`ERR_INVALID_OPTION`. `--limit <n>` caps search results (default 20) and theresponse reports the total when it cut the list. An unknown kind or a limitthat is not a positive integer MUST fail with `ERR_INVALID_OPTION`.-- **FR6 — Sources are functions a project or integration provides.** A source is- an async function that receives `{signal, package?, version?}` and resolves- to a catalog; `package` asks for one package with every version, and- `version` asks for that version's items. A project MAY set one as the- `discover` field of `astryx.config`, and each loaded integration MAY export- one as its `discover` named export. Every source is called, the project's- first and then each integration's in load order, and the same function runs- once; discover then reads the official list (FR11). A source that- throws, exceeds 30 seconds (signalled on `signal`), or returns an invalid- catalog fails alone: the others still count, and discover reports which- source failed and why. Sources only read, so `spec:AST-031`'s consent gate- does not apply to them.+- **FR6 — Sources are functions a project, an integration, or a door+ provides.** A source is an async function that receives+ `{signal, package?, version?}` and resolves to a catalog; `package` asks for+ one package with every version, and `version` asks for that version's items.+ A project MAY set one as the `discover` field of `astryx.config`, each loaded+ integration MAY export one as its `discover` named export, and a door MAY+ pass its own (`spec:AST-081` FR1), which discover names as the door's. Every+ source is called, the project's first, then each integration's in load+ order, then the door's, and the same function runs+ once; discover then reads the official list (FR11).+ A source that throws, exceeds 30 seconds (signalled on `signal`), or+ returns an invalid catalog fails alone: the others still count, and discover+ reports which source failed and why. Sources only read, so `spec:AST-031`'s+ consent gate does not apply to them.- **FR7 — The catalog shape is versioned.** A catalog is `{schemaVersion: 1,source, packages}`. `source` has `name`, `generatedAt`, and `complete`. Eachpackage has `package`, `integration` (shared by every package name thatdiff --git a/docs/specs/AST-081-global-mode/spec.md b/docs/specs/AST-081-global-mode/spec.mdnew file mode 100644index 0000000000..cc512ee1a2--- /dev/null+++ b/docs/specs/AST-081-global-mode/spec.md@@ -0,0 +1,1098 @@+---+schema_version: 4+template_version: 2+kind: system-spec+id: spec:AST-081+authority: current+archive_reason: null+superseded_by: null+approved_by: josephfarina+approved_at: 2026-10-19+phase: accepted+owners: [josephfarina]+affects_architecture: [architecture:cli-surface]+affects_families: []+affects_contributing: [contributing:cli-conventions]+affects_consumer_docs: [cli]+---++# Global mode system spec++<!-- Describe the system, not the project: present tense, what it does. No+proposals, history, pull requests, or research in the record; see+docs/contributing/spec-writing.md and report its rubric results in the pull+request. -->++## Intent++A person or an agent installs Astryx once on a computer, as the CLI package+itself, and runs it in any folder. Inside a project, every answer is the one+the release matching the project's Core gives, whichever copy of the CLI+started the run, because a template, a component doc, or an agent instruction+from another release writes code the project's Core rejects, with no error to+say so. Outside a project, the release installed for the computer answers, the+way a new project on it would, so an agent with no project files can learn+Core, its components, and the docs, and a notice says when a newer release is+out.++This record owns which release answers a run (FR1, FR2), what every command does+outside a project (FR3, FR4), how a run names the release that answered and+picks the one command name every printed command starts with (FR5), how a copy+installed for the computer learns of newer releases (FR6), where any run may+write (FR7), what each release carries for use outside a project and how the+computer-level agent text stays installed (FR8), how every copy of the CLI hands+a project's run to the release that answers there (FR9), when a run reminds its+caller to update (FR10), who answers when global and project copies meet+(FR11), and which integrations installed for the computer apply, and where+(FR12).++## Non-goals++- Which project an upgrade works on, which Core it migrates to, and what it+ reports when the CLI is older than that Core: `spec:AST-040` FR9–FR13.+- Which files hold a project's agent docs, and where `init` writes them and+ refuses to: `architecture:cli-surface` INV31.+- The official package list and how discover reads it: `spec:AST-051` FR11.+- How a host's package sets are matched to a project's pins, which+ integrations they serve, and how a run records the packages it resolved:+ `architecture:cli-surface` INV30.+- Classifying a change to released behavior that this record requires:+ `spec:AST-017`, and `architecture:cli-surface` INV10a for a refusal that+ corrects a write outside its confined root.+- What a project starter contains, and the template kind that ships it.+- Equivalent internal implementations remain valid when they satisfy this+ contract.++## Requirements++In this record, a **door** is a way to start the CLI: the `@astryxdesign/cli`+package itself, installed in a project and run through its package manager (the+project's own CLI), installed for the computer, such as with+`npm i -g @astryxdesign/cli`, or run once through a package runner, such as+`npx @astryxdesign/cli`; and a programmatic host through+`@astryxdesign/cli/host`. A **copy** is the `@astryxdesign/cli` a door starts:+the one it installed or fetched, the one a host carries, or a release in the+per-user cache that global mode installed (FR2, FR3, FR6). The **global copy**+is the CLI package installed for the computer: one in npm's global folder (a+`node_modules` whose owner holds no package.json), or in a global folder that a+package manager's own settings name (Bun's `BUN_INSTALL` or `globalDir`, Yarn's+`global-folder`, pnpm's `PNPM_HOME` or `global-dir`, and each one's default),+read the way that package manager reads them. A package kept in pnpm's store+(`<store>/v<N>/links`) is global only when such a pnpm global folder links to+it. A folder's layout alone never makes a copy global, and when the CLI cannot+tell, the copy is not global, so it runs no update check and writes no agent+text.++A folder's **project** is found the way the CLI finds the Core and the CLI it+reads there: the `@astryxdesign/core` installed in the folder or one of the four+folders above it, or a workspace's own Core package; the `@astryxdesign/cli`+installed in the folder or one of the five folders above it, resolved by the+package manager's Plug'n'Play runtime, or a workspace's own CLI package (the+folder itself, or `packages/cli` in it or one of the five folders above it); and+otherwise the nearest `package.json` at or above the folder that declares either+package, searched up to the first folder that holds version-control metadata and+never in the home folder unless the run starts there. A folder deeper than that+nearby look finds the project's Core and its own CLI the same way from that+`package.json`'s folder, as a package runner resolves the project's command from+any depth. A folder is+**outside a project** when none of these exist. A folder inside another+project, such as a repository cloned into it or a nested app, therefore+answers with the enclosing project's release. The project that an upgrade+works on is `spec:AST-040` FR9's.++- **FR1 — One CLI behind thin doors.** All behavior lives in+ `@astryxdesign/cli`. A door that runs that package directly, the project's own+ CLI or a copy installed for the computer or fetched by a package runner, runs+ the CLI itself. A programmatic host carries the `@astryxdesign/core` release+ equal to the CLI release it runs, chooses that release (FR2, FR3, FR6), and+ starts it through the host entry `@astryxdesign/cli/host`, a supported+ programmatic API whose reference doc states each input, its default, the+ result, and the errors (`spec:AST-017` FR14). A door MUST NOT pass anything to+ the CLI through an environment variable, an option, or a configuration key,+ and MUST NOT add a command, an option, or any other behavior.+ - The host entry's inputs are explicit: the arguments; the working folder;+ the command name the door's callers type (FR5); the package sets the door+ may serve, in its order of preference, and the integrations it approves for+ use outside a project, resolved by name from the package set that serves+ the run, in addition to what FR12 finds there (`architecture:cli-surface`+ INV30); the discover sources the door adds; and, when the door found the+ project's own CLI and did not run it, the reason (FR2), as text the host+ defines; this record sets no list of reasons.+ - Discover calls a door's sources after every integration's source and before+ the official list (`spec:AST-051` FR6 and FR11), and names each as the+ door's, never as an integration's.+ - A door makes one call per process. A call takes over the process's working+ folder, arguments, standard streams, and exit, so a second call in the same+ process MUST fail before running anything; calls in separate processes+ share nothing (`spec:AST-017` FR18).+ - Given the same release, Core, folder, arguments, and inputs, a command+ MUST give the same exit status, output, and file changes through every+ door, apart from the command names FR5 sets and the standard-error lines+ FR5, FR6, and FR9 define.+- **FR2 — In a project, the project's own CLI answers; without one, the copy+ that started the run.** In a folder that belongs to a project, one release+ answers every command, reads included, and every template, doc, component+ doc, hint, and agent text comes from that release.+ - When the project installs `@astryxdesign/cli`, that CLI answers, whatever+ its version, as it did before global mode (DEC-10). A run that starts in+ another copy MUST hand the run to it (FR9) before loading anything the+ project provides: its `astryx.config`, its integrations, or its Core.+ `doctor` warns when that CLI and the project's Core are different releases+ and names the command that brings them to one release.+ - When the project installs no CLI, as a project with only Core or a fresh+ clone with nothing installed, the copy that started the run answers, as+ it did before global mode (DEC-10), reading the project's Core as it+ always has. In text mode, after a successful command, at most once a day+ per project and under the same switches as FR10's notices, one line on+ standard error says so when that copy is not the project's Core release:+ `astryx: this project has no Astryx CLI installed; answered by CLI <version> while its Core is <core>. To match, run: <command>`,+ where the command adds `@astryxdesign/cli` at the Core's version with the+ project's package manager. A machine-readable result carries+ `meta.answeredBy.copy` `starting`. `doctor` warns in the same case and+ names the same command, and the setup reminder of a project that has not+ run `init` names it first, then `astryx init`.+ - The release equal to the project's Core (the matched release) is the+ version of the Core the folder reads, else the Core version the project's+ lockfile records, else the newest published release that the Core range+ the project declares allows; a project that records no Core is matched by+ the CLI it locks or declares, in the same order.+ - When the project's own CLI is installed but cannot start, the matched+ release answers: the copy that started the run when it is that release,+ otherwise the release in the per-user cache, installed there through the+ package manager the first time a project needs it. The package manager is+ started without a shell, and a declared Core range is read only when it is a+ plain version range, so nothing a project declares reaches a shell. While a+ release installs, or while the run waits for another run installing it, a+ text-mode run prints one line on standard error saying so; a+ machine-readable run prints none. An install that a live run is still making+ is waited for, a lock its run left when it stopped is taken over, and a+ cached release whose files are damaged is installed again. An install that+ has not finished within a generous bound is a release that cannot be+ obtained (below), never a stopped process. No install outlives the run that+ started it: it ends when that run ends, however the run ends, and its record+ of npm's process is removed then, since that number can later name another+ process. A run that takes over a stopped run's lock ends the install that+ lock records only when the process is surely it: its arguments are exactly+ npm, or node running npm's entry file, installing `@astryxdesign/cli` at the+ lock's release, it started after the lock was taken, and the lock is younger+ than any install may take. npm's process title, which the system may report+ as one argument, is read as its arguments. Otherwise it takes the lock over+ and leaves the process alone.+ - `astryx upgrade` follows the same rule: the project's own CLI runs its+ codemods, and `spec:AST-040` FR13 defines what it reports when it is older+ than the installed Core; in a project with no CLI of its own, the copy that+ started the run runs its own codemods, as before global mode.+ - When a door finds the project's own CLI and declines to run it, it passes+ the reason (FR1). The release equal to that CLI's version then answers in+ its place when the door can run it; otherwise the copy that started the+ run answers, announced as for a release that cannot be obtained, and the+ warning names the reason the project's CLI was declined.+ - When the release this requirement names is not installed and cannot be+ obtained (it cannot be fetched, the registry does not have it, no+ published release fits the declared range, or the cache cannot be+ written), the run MUST be answered by the copy that started it, as before+ global mode. It MUST be announced: in text mode one line on standard error,+ `astryx: could not get Astryx <release> to match this project's Core (<reason>); answering with CLI <version> instead`,+ and in a machine-readable result `meta.answeredBy.copy` is `fallback`.+ No other release answers, and nothing falls back while the matched+ release can be obtained. A failed install is recorded in the per-user+ cache, by release, and no copy using that cache starts it again for 2+ minutes after a first failure, or 10 minutes after a second failure in a+ row; a successful install forgets it. So an offline run prints at most one+ line saying it installs, and the warning says when it was last tried.+ `ERR_VERSIONS_UNAVAILABLE` is for a run nothing can answer, such as a+ command that needs Core outside a project that cannot install it (FR3).+- **FR3 — Outside a project, the running release answers as a new project+ would.** Outside a project, every copy answers itself, the global copy+ included (FR6, FR9). The answering release MUST answer as it would in a new+ project that installs only that release of Core, the computer-level+ integrations (FR12), and any integration a programmatic host approves (FR1).+ Outside a project, or in a project with nothing+ installed (FR2's copy that started the run, such as in a fresh clone), every+ command that needs Core answers from the carried Core: the+ `@astryxdesign/core` release equal to the answering CLI, beside it, carried by+ its door (FR1), or kept in the per-user cache, where a copy that carries none+ installs it the first time a command needs it. The global copy also installs+ its own release's Core there in the background, on any run while none is+ beside it or cached (FR6), so commands that read Core work offline after one+ online run. A project's installed Core is always read in its place, from any+ depth. When the carried Core cannot be installed, those commands fail with+ `ERR_VERSIONS_UNAVAILABLE` before any write, and in a project the message says+ the project has no Core installed and to install its dependencies; the+ exception is an open `search`, which answers from the domains that need no+ Core and says what it skipped and why: `meta.partial` in a machine-readable+ result, and one line on standard error in text mode. `doctor`, `swizzle`, and+ `upgrade` judge or change a project and MUST NOT read the carried Core.+ Output outside a project MUST NOT give advice that works only inside one, such+ as a step that sets up, configures, or refreshes a project the folder does not+ have.+- **FR4 — Every command declares what it does outside a project.** Every+ command and subcommand MUST declare one of three values in its command doc,+ and `astryx manifest` MUST publish that value as the command's+ `outsideProject`:+ - `same`: it gives the answer it gives in a new project (FR3).+ - `refuse`: it writes nothing and fails before doing any work, naming what it+ needs, an app project or an integration package.+ - `own`: it does something else outside a project, which its command doc+ states and a test of its own covers.++ A command that only groups subcommands declares nothing. A refusal fails with+ `ERR_PROJECT_REQUIRED`, except that a command whose released versions refuse+ outside a project with another error code keeps that code until a declared+ minor changes it; that change, and any other change to what a released command+ does outside a project, is classified under `spec:AST-017`. `doctor` is `own`:+ outside a project it checks the computer, reporting the Node version, the+ release that answered and the newest release it knows of, and whether the+ computer-level agent text (FR8) is present and current, and it never fails a+ check because the folder has no project. `swizzle` is `refuse`, even with a+ carried Core.++- **FR5 — Every answer names who answered, and one picker names every printed+ command.**+ - Every successful machine-readable result MUST carry `meta.answeredBy`:+ `cli`, the answering CLI's version; `core`, the version of the Core the run+ pairs with (the project's installed Core, or the carried Core when the+ project has none or the folder is outside a project), or `null` when there+ is none; and `copy`, which is `project` for the project's own CLI,+ `starting` for the copy that started the run in a project with no CLI of+ its own, `matched` for the release FR2 matches to the project's Core when+ the project's own CLI cannot start, `carried` outside a project, and+ `fallback` when the matched release could not be obtained and the copy that+ started the run answered instead (FR2). A release that+ predates this field answers without it, and no door adds it.+ - In text mode, when `copy` is `matched` or `carried`, the run MUST print one+ line on standard error naming the CLI and Core versions and which copy+ answered; a `fallback` run prints FR2's warning line instead, and a+ `starting` run prints none, only FR2's daily hint. A+ run started in the project's own CLI prints no such line, and a run another+ copy hands to it prints the one line FR9 defines.+ - Every command the CLI prints or writes for its caller to run MUST start+ with the command name that one picker chooses for the folder the command+ runs in. The picker takes the first of these that applies:+ 1. the command that the integrations the run loads declare for running the+ CLI, such as `acme astryx` for a company's own command-line tool;+ 2. the name passed by the door that started the run (FR1);+ 3. the package manager's name: the project's run prefix when the project's+ own CLI answers, `astryx` when the global copy or a release it keeps+ answers outside a project, and otherwise the package runner with the+ CLI package pinned to the answering version, such as+ `npx @astryxdesign/[email protected]`.+ - The computer-level agent text (FR8) belongs to no folder and names no+ release, so its commands start with the name of the door that wrote it,+ and otherwise with `astryx`, the command of the global copy, which answers+ outside a project itself and hands a project's run to that project's+ release (FR9). No integration's `cliCommand` applies+ to it.+ - The picked name takes the place of the command's leading `astryx` and, run+ from that folder, MUST reach the same choice of release (FR2, FR3, FR9). A+ printed command MUST NOT run, through a package runner, the CLI package+ without a version or a package other than the CLI.+ - An integration MAY declare in its manifest, as `cliCommand`, the command+ that runs the CLI for its users: a non-blank single line of at most 120+ characters, with no surrounding spaces and no Astryx agent-docs marker text+ (`ASTRYX:START`, `ASTRYX:END`), that starts the CLI through a door following+ FR1 and FR2. With no declaration, the picker goes on to the door's name.+ Integrations that declare the same command agree. When the integrations the+ run loads declare different commands, the picker takes the package manager's+ name, even when a door started the run, and `doctor` warns, naming each+ integration and the command it declares. A declaration of any other form+ counts as absent, never withdraws the integration's other contributions, and+ `doctor` warns about it; `doctor integration validate` and+ `integration check` report it as a note (`invalid_cli_command`) beside+ their issues, which fails nothing.+ - The picker names every command the CLI prints or writes: hints and next+ steps, errors and their suggestions, `doctor` fixes, help, docs moves+ (`spec:AST-047`), recommended commands (`spec:AST-048`), the project's+ agent-docs block, the computer-level agent text (FR8), and the setup+ reminder wherever it is printed. No surface spells a command name of its+ own.+ - Docs, guides, agent text, and the text an integration supplies, such as+ its docs and its agent-doc lines, write every CLI command bare, beginning+ `astryx`; the CLI puts the picked name in its place when it prints or+ writes that text. A step that installs a door, or starts one by its own+ name, is not a CLI command and stays as written.+ - Machine-readable output, error envelopes included, carries every command+ bare, beginning `astryx`, and never a picked name.+ - A command that finishes work with another release names that release+ (`spec:AST-040` FR13).+- **FR6 — The global copy tells its user about newer releases and installs+ none; projects are never touched.** Outside a project, the global copy+ answers with its own installed release. No door installs a newer release for+ the computer, switches to one, or changes the package manager's installation+ of the global copy; its user upgrades it with the package manager, which+ FR10's notice names.+ - The global copy checks the release the package registry tags `latest` for+ `@astryxdesign/cli`, and the Node range that release declares, at most+ once in any 24 hours, never sooner than 24 hours after its first run, and+ only during a run. The check runs in the background, at most one at a+ time; no command waits for it, fails because of it, or changes its output+ or exit status because of it. It records what it found, and when, in the+ per-user state file (FR7), and installs nothing.+ - On a run while it carries no Core beside it and none is cached for its+ release, the global copy installs that Core into the per-user cache from a+ detached step it starts as the run ends, as FR3 needs: never when `CI` is+ set as below, never blocking or changing a command or holding anything the+ command's caller waits on, and a failure is silent and waits out FR2's+ backoff before a later run's step tries again. It never runs on Windows,+ where a detached process inherits the caller's open pipes; there a command+ that reads Core installs it the first time it needs it. This installs the+ global copy's own release's Core only, never a newer release.+ - No check runs when the environment variable `CI` is set to a value other+ than empty, `0`, or `false`, or when `NO_UPDATE_NOTIFIER` is set to any+ value. Astryx defines neither: `CI` is the platform convention continuous+ integration services set, and `NO_UPDATE_NOTIFIER` the one command-line+ tools share to silence update notices; each is read only for that shared+ meaning (`spec:AST-017` FR14).+ - A release requested by version, such as `npx @astryxdesign/cli@<version>`,+ runs exactly that release outside a project, with no check; inside a+ project, FR2 and FR9 decide which release answers. A copy a package runner+ fetches runs no check.+ - Updates have no other control; the package manager's registry, proxy, and+ offline settings apply to the check.+ - No door updates a project or installs into one. A project's release that is+ behind the newest gets FR10's notice, and `doctor` reports it; neither+ installs anything.+- **FR7 — Writes stay inside named places.** Every file the CLI or a door+ writes MUST land in one of these places; a write anywhere else MUST be+ refused before anything is written (`ERR_PATH_TRAVERSAL`,+ `architecture:cli-surface` INV10):+ - the operation root: the folder the command runs in, or a folder above it+ when the record that owns the command's writes says so, such as the project+ root of an upgrade (`spec:AST-040` FR9), the project that holds the theme+ module (`spec:AST-050` FR2), and the folder where `init` writes agent docs+ (`architecture:cli-surface` INV31);+ - the per-user cache directory of the platform (a cache or configuration+ folder that an environment setting points at counts only when it is an+ absolute path), for saved discover answers (`spec:AST-051` FR8) and for the+ releases global mode installs into a project's run (FR2, FR3);+ - the platform's temporary directory, for scratch work such as building or+ verifying a package;+ - the per-user configuration directory of the platform, for the documented+ settings of the computer-level agent text and the per-user state file,+ `astryx/state.json`, which holds what the update check found and when+ each notice last printed (FR6, FR8, FR10);+ - the computer-level agent text (FR8), its links, and its copy, written by+ `astryx init --user` and by the global copy keeping that text installed,+ in the background, as FR8 states; no other command writes them, and no+ package install script does.++ No run writes a project's agent docs into the home folder or a settings folder+ in it (`architecture:cli-surface` INV31); the computer-level agent text above+ is not a project's agent docs, and INV31 says so. When a door fetches a+ release through the package manager, the package manager's own files follow+ its own settings. `architecture:cli-surface` INV10a classifies a refusal that+ corrects a write a released version made outside these places.++- **FR8 — Everything global ships inside the release.** The agent text, the+ official package list (`spec:AST-051` FR11), and the project starters ship+ inside each CLI release. Each is generated from the repository when the+ release is built and is never fetched at run time or edited by hand, and a+ check MUST fail when a committed copy no longer matches the repository.+ - Every agent text a release prints or writes names only the command name FR5+ picks for its surface. The computer-level text is its own short text: it+ tells an agent that Astryx is on the computer, when it is relevant, and to+ start with `astryx search`; it names no version, no release-specific+ command or prop, and only entry points every release keeps (`search`,+ `docs`, `component`, and the like), so an older copy never misleads.+ - The computer-level text is one file, `.agents/skills/astryx/SKILL.md` in+ the home folder, which most agent tools read. The computer-level agent+ files table below names each other folder it reaches: a folder link to its+ folder with a relative target, a junction on Windows, or a managed copy+ where a link cannot be made or the tool skips links. A refresh rewrites the+ one file; the links follow it. It is installed with the global copy: on the+ global copy's first run, and on the first run after the global copy's+ installed release changes, as when its user upgrades it, the global copy+ writes or refreshes it in the background, so no command waits for it or+ prints anything about it, and a package's install scripts never write it.+ - `astryx init --user` writes or refreshes it in the foreground, in any+ folder (FR9). `astryx init --user --remove-agents` removes the file, every+ link the CLI made, and every managed copy, and records that the+ computer-level text is not wanted. The global copy honors that choice, and+ writes nothing, until `astryx init --user` runs again.+ - The settings file is `astryx/settings.json` in the per-user configuration+ directory (FR7): `computerAgentText.install`, `true` or `false`, and+ `computerAgentText.links`, the links the CLI made, so removal removes+ exactly those. A missing file means install. No environment variable or+ option changes it.+ - The file and each managed copy record, inside their managed markers, a hash+ of their text. A file whose text no longer matches its recorded hash, or+ that records none, was edited by a person and is never overwritten or+ removed; a file without the markers is never changed; no write follows a+ link in a file's place; and nothing the CLI did not create at a table+ folder is replaced. `init --user` names each such path as kept and why, and+ `doctor` reports it, and any link whose skill folder is missing.+ - Every project starter a release ships scaffolds, installs, and builds with+ that release, and a check MUST prove it for every starter before the+ release ships. A scaffold pins every Astryx package to the release that+ made it and declares the CLI, so the project's own copy answers from then+ on (FR2).++- **FR9 — Every copy hands a project's run to the release that answers there.**+ Every copy of the CLI, whether installed in the project, installed for the+ computer, fetched by a package runner, or carried by a programmatic host, that+ starts a run in a folder belonging to a project MUST hand the run to the+ release FR2 names when it is not that release itself: to the project's own CLI+ when the project installs one, whatever its version, and to the matched+ release when that CLI cannot start. A project with no CLI of its own is+ answered by the copy that started the run, with no hand-off. This holds+ whatever release the copy is and whatever version the command line asked for.+ Outside a project, every copy answers itself (FR3).+ - A copy hands the run off before it loads anything the project provides+ (FR2). It does not hand off when it is itself the release FR2 names, or+ when the door that started it declined the project's CLI (FR2).+ - A command that acts on the computer rather than the folder it runs in,+ `astryx init --user` (FR8) and `astryx docs global` with its pages, the+ docs of global mode itself, is never handed to a project's release: it is+ answered as outside a project wherever it runs, so those docs read the same+ inside a project whose release predates them, and its standard-error line+ says it answered for the computer.+ - `astryx --help` carries one line, and the manifest (FR4) a `globalMode`+ field with `docs` and `summary`, that say what a run may do beyond its+ command, the hand-off, the daily check (FR6), and the agent skill (FR8),+ and point to `astryx docs global` (`spec:AST-017` FR14).+ - A run is handed off at most once. The copy a run is handed to makes the+ same choice and finds itself, so a run never returns to a copy it has+ left.+ - The copy the run is handed to receives what it would receive if started+ directly in that folder: the same arguments, working folder, and standard+ input, output, and error, with nothing added to its environment, options,+ or configuration (FR1). The run ends with that copy's exit status, or the+ signal that ended it. A termination or hangup signal sent to the copy that+ started the run reaches the copy it handed the run to. A SIGINT that+ reaches only the starting copy is forwarded if the handed-off CLI is still+ running 5 seconds later, so an interrupt the whole process group got (a+ terminal's Ctrl-C) reaches a CLI that stops within that time exactly once.+ On Windows the starting copy forwards no interrupt.+ - When the project's own CLI cannot be started, the matched release answers+ (FR2). When the matched release cannot be obtained, the copy that started+ the run answers, announced (FR2).+ - In text mode, a run handed to the project's own CLI prints exactly one+ line on standard error, naming the version of the project's CLI that+ answered and the version of the copy the run started in. A run handed to+ any other release prints exactly one line too: the FR5 line, which the+ release that answers prints, or, for a release that predates it, the copy+ that handed the run over. A machine-readable run prints no such line; its+ `meta.answeredBy` names the release that answered (FR5) when that release+ carries the field.++- **FR10 — A finished command tells its caller about a newer release.** After+ a command finishes with exit status 0, in text mode, the copy that started+ the run prints each notice below that applies on standard error, each at most+ once in any 24 hours. Each notice is two lines, the first naming what is+ newer and the second the exact command that upgrades it:+ `A new release of Astryx is available: <current> → <newest>` and+ `To upgrade, run: <command>`. When the newest release declares a Node range+ the computer's Node does not satisfy, the second line reads+ `To upgrade, install Node <range> (this computer runs Node <version>), then run: <command>`.+ - Outside a project, when the global copy answered and is older than the+ newest release the check found (FR6): the command is that of the package+ manager whose global install holds the global copy, read from where it+ lives: `npm i -g @astryxdesign/cli@latest`,+ `pnpm add -g @astryxdesign/cli@latest`,+ `yarn global add @astryxdesign/cli@latest`,+ `bun add -g @astryxdesign/cli@latest`, or+ `volta install @astryxdesign/cli@latest`, and npm's when none is recognized.+ A copy npm installed under a prefix that is not one of npm's defaults+ (Node's own prefix, `/usr/local`, `/usr`, or `%APPDATA%\npm` on Windows) is+ upgraded into that prefix:+ `npm i -g --prefix <prefix> @astryxdesign/cli@latest`, with `~` for the home+ folder. A global folder a package manager's settings move, such as Bun's+ `BUN_INSTALL` or Yarn's `global-folder`, counts as global (the global copy,+ above), and its plain command reinstalls there, since the package manager+ reads the same settings.+ - Inside a project, when the release that answers it is older than the newest+ release the check found: the command installs `@astryxdesign/core` and+ `@astryxdesign/cli`, so a project that installed only Core gets its own CLI+ too, at the newest release with the project's own package manager, then runs+ `astryx upgrade --from <current> --apply` with the command name FR5 picks+ for that release, as `<install command>, then <upgrade command>`.+ - In any folder, when the first `astryx` command on the search path is an+ Astryx CLI release that predates the hand-off, so it answers every run+ started through it with its own release: the first line reads+ `The astryx command on this computer runs CLI <version>, which answers every folder itself.`+ and the command upgrades it with the package manager that installed it.+ This notice needs no check.+ - No notice prints in a machine-readable run, after a command that fails,+ or when `CI` or `NO_UPDATE_NOTIFIER` turns the check off (FR6). A notice+ prints whether or not standard error is a terminal. Prerelease and canary+ versions are never reported as behind. No notice changes a command's+ output or exit status.+ - The time each notice last printed is kept in the per-user state file+ (FR7), for the global copy, per project, and for the old command; a time+ that cannot be recorded keeps the notice from printing, and a run handed+ to a release that also prints notices prints no second one.+ - `doctor` reports each: outside a project, the global copy's release beside+ the newest with the same command; in a project, the project's release+ beside the newest with the same commands; and, in every folder, an+ `astryx` command that predates the hand-off.+- **FR11 — Global and project copies meet by these rules.** Every case below+ follows FR2, FR3, FR6, FR9, FR10, and FR12; the table names who answers, what+ the run prints on standard error in text mode, and the test that proves the+ row. A contributor adding a door, an install layout, or a platform adds a row+ and its test. A copy the CLI cannot change, such as a release that predates+ the hand-off, is reported, never worked around. The cases that depend on an+ operating system's own file system run in the test suite for their path rules+ and, on that system, only in the cross-platform smoke workflow, which a+ maintainer starts by hand.+ - `doctor` lists every `astryx` command found on the search path, in order,+ and warns when the first one is not the Astryx CLI or is a release that+ predates the hand-off, naming the command that replaces it.+ - A run that installs a release holds a lock in the per-user cache that+ names its holder and computer, and renews it every 10 seconds while the+ package manager works. A lock whose holder on this computer no longer+ runs is taken over at once; a lock from another computer is taken over+ once a waiting run has seen it go unrenewed for 60 seconds.+ - Paths are compared without regard to letter case on platforms whose file+ systems ignore it, and a project is found from the physical folder, so a+ link to a project folder answers as the folder does.++- **FR12 — Integrations installed for the computer apply outside projects, and+ only there.** A **computer-level integration** is an integration package, one+ that ships exactly one root `astryx.integration.*` manifest, installed in the+ same install root as the CLI installed for the computer: the folder whose+ `node_modules` holds that CLI package, such as a package manager's global+ folder beside a global copy, or the package set a tool installs together and+ runs the CLI from, such as a door's runtime holding the CLI, Core, and an+ integration. When that root has a `package.json`, the packages it declares are+ read; otherwise every package directly in its `node_modules`, scoped ones+ included. A package manager that installs each global package in a folder of+ its own, as pnpm 11 and later do, has every such folder read, provided one of+ them installs that CLI. The CLI and Core packages are never integrations of+ it. A package runner's temporary install and the per-user release cache are+ not install roots. A door needs no host entry input for them (FR1).+ - Outside a project, the copy that answers loads the computer-level+ integrations installed beside it as a project loads its own: their+ components, templates, docs, themes, codemods, discover sources, and+ `cliCommand` (FR5) apply, with the same validation and the same provider+ identity rules. One whose declared peer range for `@astryxdesign/core` or+ `@astryxdesign/cli` excludes the answering release is skipped.+ - Inside a project, only the project's own integrations load: configured,+ installed, or being authored there. A computer-level integration adds no+ component, template, doc, theme, codemod, discover source, or command name+ there, because a printed import or command would name a package the project+ does not install. The only use of them inside a project is a listing:+ `discover` and `doctor` load the manifest of each one the project does not+ install, and nothing it contributes, to list it as available. `discover`+ lists each computer-level integration the project does not install, whose+ peer range admits the release that answers there and whose manifest loads,+ among the packages the project could add, with source+ `installed for this computer` and the project's install command. Those are+ the integrations beside the copy that answers when it was installed outside+ the project, otherwise beside the first `astryx` on the search path that is+ installed for the computer. The command name a door passes still applies+ (FR5).+ - When a project installs the same integration, by package name, the+ project's copy is the only one that loads, inside the project and in any+ folder whose project it is. Outside a project, a folder that loads an+ integration itself, such as that integration's own source, uses its own+ copy.+ - `doctor` outside a project lists each computer-level integration it uses and+ each the folder loads its own copy of, and warns about each it skips or+ cannot load, naming why; inside a project, it lists the ones `discover`+ lists as available, with the project's install command.++### Computer-level agent files++| Folder in the home folder | Reached by | When | Agent tool |+| ------------------------------------------------------------------------- | ---------- | ----------------------------------------------------- | ------------------------ |+| `.agents/skills/astryx` | the file | always | most agent tools |+| `.claude/skills/astryx` | link | always | Claude Code |+| `.kiro/skills/astryx` | link | when `.kiro` exists | Kiro |+| `.codeium/windsurf/skills/astryx` | link | when `.codeium/windsurf` exists | Windsurf |+| `.letta/skills/astryx` | link | when `.letta` exists | Letta |+| `Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/skills/astryx` | link | when `Library/Developer/Xcode/CodingAssistant` exists | Xcode's coding assistant |+| `.config/agents/skills/astryx` | link | when `.config/agents/skills` exists | Kimi |+| `.continue/skills/astryx` | copy | when `.continue` exists | Continue |++The file is a regular file and a skill whose frontmatter is strict YAML and+whose `name` is its folder's name. Each link is a link to the folder, never to+the file, since some tools drop a linked skill file, and its target is+relative, so it survives a moved or synced home folder. A tool that reads the+shared folder and its own lists the skill once. Continue's scanner skips links,+so it gets the one managed copy. The CLI never writes a folder another tool+manages, such as Codex's or Muse's own skill stores, never edits an agent+tool's configuration, and writes no always-on instructions file. A tool that+reads no skill folder, such as Aider, gets nothing; a person who uses an agent+with another skills folder links it to `.agents/skills/astryx` themselves.++### Who answers when global and project copies meet++| Case | Who answers | What prints (text mode) | Test |+| ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |+| G1 Global copy newer than the project's own CLI, which matches its Core | The project's own CLI | `answered by this project's CLI <p>, handed over from CLI <g>` | `global-local.test.mjs › G1` |+| G2 Global copy older than the project's own CLI | The project's own CLI | The same hand-off line | `› G2` |+| G3 The project's CLI differs from its Core | The project's own CLI (DEC-10) | The hand-off line; `doctor` warns and names the align command | `› G3` |+| G4 Core only, no CLI | The copy that started the run | FR2's daily hint when it is not the Core's release; `copy` is `starting`; nothing installed | `› G4` |+| G5 Fresh clone: lockfile, nothing installed | The copy that started the run | FR2's daily hint naming the Core the lockfile records; nothing written | `› G5` |+| G6 Lockfile and installed Core disagree, in a project whose own CLI cannot start | The release equal to the installed Core | The matched line | `› G6` |+| G7 Workspace member with its own Core under a root CLI | The root CLI, as for any member (DEC-10) | The hand-off line | `› G7` |+| G8 Folder inside another project, such as a nested app or a cloned repository | The enclosing project's release (the released read reach; answering for the folder itself waits for a minor) | As for the enclosing project | `› G8` |+| G9 Outside a project | Every copy answers itself, the global copy included | `answered by CLI <v> with Core <v>, outside a project` | `› G9` |+| G10 A version typed on a package runner | Outside a project: exactly that release; in a project: the project's release | The outside or hand-off line | `› G10` |+| G11 A global copy that predates the hand-off, in a project | That old copy, which this record cannot change | Nothing from that copy; FR10's reminder from any newer copy, and `doctor`, name `npm i -g @astryxdesign/cli@latest` | `› G11` |+| G12 Two global installs, such as npm and pnpm | The first on the search path, which answers itself | As for that case; `doctor` lists both | `› G12` |+| G13 An `astryx` earlier on the search path that is not the Astryx CLI | That other program | `init --user` and `doctor` warn | `› G13` |+| G14 A Node version manager switches Node, so each Node has its own global copy | That Node's own global copy | As for that case | `› G14` |+| G15 A project whose package manager is pinned through a package manager shim | As for that project | As for that project; releases install in the cache folder, never the project | `› G15` |+| G16 Global copy installed with administrator rights, run by a person | As for that case; nothing is written to the install folder | As for that case | `› G16` |+| G17 The per-user cache cannot be written | Outside a project and in a project with only Core: the global copy; in a project whose own CLI cannot start: the global copy | For the last, FR2's warning line naming the cache folder; `copy` is `fallback` | `› G17` |+| G18 Home unset, or cache and configuration folders set by environment | Unchanged; an absolute folder setting is used, a relative one is ignored | As for that case | `› G18` |+| G19 Continuous integration (`CI` set) with a fresh home each run | As for that case; no update check | No notice | `› G19` |+| G20 A container whose home folder is read-only | As for G17; the computer-level text is not written | As for G17 | `› G20` |+| G21 A cache shared by several people or computers | One install per release at a time; another computer's lock is taken over once it goes unrenewed for 60 seconds | As for that case | `› G21` |+| G22 The project's release is older than the newest | The project's release | FR10's project notice after the command, once a day per project | `› G22` |+| G23 The newest release needs a newer Node | The global copy | FR10's notice, naming the Node first; `doctor` the same | `› G23` |+| G24 A link to a project folder | As for the folder it links to | As for that folder | `› G24` |+| G25 A file system that ignores letter case | As for the folder, whatever case was typed | As for that folder | `› G25` (path rules); the file system itself: the cross-platform smoke workflow only (macOS, Windows) |+| G26 Windows paths and installs | The same rules; releases install through `npm.cmd` with the time limit | As for that case | `› G26` (path rules); Windows itself: the cross-platform smoke workflow only |+| G27 A package script, which puts the project's own commands first | The project's own CLI, whatever its version | As for that case | `› G27` |+| G28 A Yarn Plug'n'Play project, whose own CLI Astryx cannot see | The copy that started the run | FR2's daily hint with Yarn's command | `› G28` |+| G29 A package runner that reuses the global install | As the global copy | As for that case | `› G29` |+| G30 `astryx init --user` inside a project | The starting copy, for the computer | `answered by CLI <v> with Core <v>, for this computer` | `› G30` |+| G31 A cached release a project whose own CLI cannot start needs is damaged or removed | The release, installed again | As for that case; when it cannot be installed, FR2's warning line and the starting copy | `› G31` |+| G32 A workspace whose own CLI package sits beside its own Core package, such as the Astryx repository | The workspace's own CLI | As for that case | `› G32` |+| G33 The global copy is older than the newest release | The global copy | FR10's notice after the command, naming the package manager that installed it, once a day | `› G33` |+| G34 `NO_UPDATE_NOTIFIER` or `CI` set | As for that case; no update check | No notice | `› G34` |+| G35 Outside a project, with an integration installed beside the global copy | The global copy, with that integration loaded | As for that case | `› G35` |+| G36 Inside a project that does not install an integration installed for the computer | The project's release, without it | As for that case; `discover` and `doctor` list it as available with the project's install command | `› G36` |+| G37 A project that installs the same integration as the computer | The project's release, with the project's copy only | As for that case | `› G37` |+| G38 An integration installed for the computer whose peer range excludes the answering release | The global copy, without it | As for that case; `doctor` warns | `› G38` |+| G39 A door's package set: the CLI and an integration installed together in one root | That copy, with the integration loaded outside a project | As for that case | `› G39` |+| G40 pnpm global folders: one shared folder, or a folder per package | The global copy, with the integrations in every such folder loaded outside a project | As for that case | `› G40` |+| G41 Outside a project, in an integration's own source folder | That copy, with the folder's own copy of the integration | As for that case; `doctor` names the computer's copy as not used, without a warning | `› G41` |+| G42 Inside a project, an integration installed for the computer that the project's release excludes, or that fails to load | The project's release | As for that case; neither `discover` nor `doctor` offers it | `› G42` |+| G43 Inside a project with only Core that a door's package set answers | That copy | `copy` is `starting`; its integrations are offered as available | `› G43` |+| G44 A global copy npm installed under its own prefix, such as `npm i -g --prefix ~/.local` | The global copy | As for that case; the notice and `doctor` upgrade into that prefix, and integrations installed there apply | `› G44` |+| G45 The computer-level agent text on the global copy's first run | The global copy | As for that case; one file, Claude Code's folder linked to it, a folder the CLI did not create kept and named by `doctor`, and `--remove-agents` removing the file and the link | `› G45` |+| G46 `astryx docs global` inside a project whose release predates it | The starting copy, for the computer | `astryx: answered by CLI <version> with Core <version>, for this computer` | `› G46` |+| G47 A project whose own CLI is newer than its Core, online or offline | The project's own CLI; nothing is fetched | The hand-off line; `copy` is `project` | `› G47` |+| G48 Offline, a project whose own CLI cannot start | The starting copy | FR2's warning line, once; `copy` is `fallback` | `› G48` |+| G49 Offline, a release a project whose own CLI cannot start needs failed to install; run again from the same or another copy | The starting copy | FR2's warning line, saying when the install was last tried; no install starts for 2 minutes, then 10 after a second failure; a success forgets it | `› G49` |+| G50 A global copy in a Bun global folder moved with `BUN_INSTALL`; an app in a folder that ends in `install/global` | The global copy while `BUN_INSTALL` names the folder; the app's own CLI for the app | `bun add -g` reinstalls there; the app is never global | `› G50` |+| G51 A global copy in a Yarn 1 global folder named by `global-folder`; an app made with `yarn add` alone | The global copy while Yarn's settings name the folder; the app's own CLI for the app | `yarn global add` reinstalls there; the app runs no update check and writes no agent text | `› G51` |+| G52 The global copy with no Core beside it and none cached (not on Windows) | The global copy | A detached step installs its Core into the cache after a run (never in CI or on Windows); offline, the failure waits out the backoff | `› G52` |+| G53 pnpm's global virtual store: a project's own CLI kept in the store's `links` folder | The project's own CLI, not a global copy; a copy a pnpm global folder links to is global | The project run starts no update check and writes no agent text | `› G53` |+| G54 A folder more than five levels deep in a project with its own CLI | The project's own CLI | The hand-off line; no hint | `› G54` |+| G55 A `--json` run in a fresh clone while the global copy's Core step runs | The global copy | Returns at once with clean JSON; the step starts as the run ends | `› G55` |+| G56 An open `search` outside a project before the release's Core is cached | The global copy | Gets the Core as `component` does; when it cannot, `meta.partial` names the skipped domains and the reason, with one standard-error line | `› G56` |+| G57 A folder more than four levels deep in a project with only Core | The copy that started the run | Reads the project's Core, never the carried one; `meta.answeredBy.core` names it | `› G57` |+| G58 An interrupt sent to the copy that started a handed-off run alone, or to its whole process group | The project's own CLI | Alone: forwarded once after 5 seconds; group: received once, not forwarded to a CLI that stopped in time; the run ends with that CLI's exit status or signal | `› G58` |++### Platform support++- Supported feature/engine floor: every operating system, shell, and package+ manager the CLI supports, including the workspaces and install layouts of+ npm, pnpm, Yarn (Plug'n'Play included), and Bun, and the package runner each+ provides.+- Unsupported behavior: a door that cannot obtain the release FR2 names fails+ before any write; a global copy that cannot reach the registry answers as+ always, and prints no notice (FR6). In a Yarn Plug'n'Play project, a+ copy cannot see the project's own CLI without running the project's+ loader, which FR2 forbids before the hand-off, so the release equal to the+ project's Core answers from the per-user cache instead; it is the same+ release whenever the project's CLI matches its Core.+- Browser evidence: not applicable; the contract is CLI output, exit status,+ and file changes.++## Current-state impact++- A CLI installed for the computer answers in every folder, inside projects that+ install their own copy too, and pairs its templates, docs, and agent text with+ the project's Core. A project whose CLI and Core are on different releases+ answers with the CLI's templates and docs and the Core's components. A package+ runner runs a CLI package installed for the computer in place of fetching one,+ at whatever release it was installed, and that copy never updates. A version+ requested on a package runner's command line answers inside a project, and in+ a package with no Astryx inside a project, a package runner fetches the newest+ CLI instead of running the project's. A project with Core and no CLI, and a+ fresh clone with nothing installed, answer with whatever CLI started the run,+ or fail. Outside a project, the commands that need Core fail, hints name the+ CLI package without a version, refusals use several error codes, nothing names+ the release that answered, and no check runs a command outside a project.+ Printed command names come from the package manager alone; many hints, errors,+ `doctor` fixes, docs, and the setup reminder print a fixed name instead; an+ integration has no way to name the command its users run; the computer-level+ agent text is written only when a person runs `astryx init --user`; no run+ tells anyone that a copy or a project is behind; `doctor` does not list the+ `astryx` commands on the search path; and an integration installed for the+ computer applies nowhere. Each of these departs from FR1–FR12.+- The CLI provides FR2–FR9 through the doors that run the CLI package directly.+ The parts that need the programmatic host entry arrive with it: FR1's host+ entry, its inputs, and its one-call rule; FR2's clause for a door that+ declines the project's CLI; FR3's integrations a host approves; the door name+ in FR5's picker; and+ `architecture:cli-surface` INV30. The official list FR8 ships is+ `spec:AST-051` FR11's. The project starters FR8 ships arrive with the template+ kind that ships them.+- Follow-up, next minor release: `invalid_cli_command`, a malformed+ `cliCommand` (FR5), becomes a validate warning, which+ `integration check --strict` fails on. This release reports it as a note+ outside the issues, since `--strict` fails on every warning and a new failure+ code joins only in a minor (`architecture:cli-surface` INV35).+- Follow-up, next minor release, breaking: the release equal to the project's+ Core answers even when the project's own CLI is another release, and answers+ a project with only Core instead of the copy that started the run (DEC-10).+- `architecture:cli-surface` records the release-choice stage before dispatch+ (FR2, FR9), the per-user writes outside a project root in INV10 (FR2, FR7,+ FR8), the run-level standard-error lines in INV12 (FR2, FR5, FR10), the+ computer-level integrations beside INV14's autolinking (FR12),+ `outsideProject` in INV7 (FR4), `ERR_PROJECT_REQUIRED` and+ `ERR_VERSIONS_UNAVAILABLE` in INV3 (FR2, FR4), `meta.answeredBy` in INV2+ (FR5), the picker's command name in INV22's hints (FR5), and the+ computer-level text in INV13's single rendered source (FR8). The host entry's+ inputs (FR1, FR2) are recorded there with the host entry.+- No record lists the integration manifest's fields. `cliCommand` (FR5) is an+ integration-level field, which INV24 allows, and the integration authoring+ reference documents it beside the other fields: its accepted values, its+ place in the picker's order, and what happens when integrations disagree+ (`spec:AST-017` FR14).+- `architecture:cli-surface` INV30 keeps how a host's package sets are+ matched, enumerated, and recorded; which release answers a hosted run, the+ host entry's inputs, and the standard-error lines of a hosted run are FR1,+ FR2, and FR5's.+- `spec:AST-047` FR7 and `spec:AST-048`'s platform support take the command+ name they print from FR5, and `spec:AST-051` FR6 admits a door's sources+ (FR1).+- `contributing:cli-conventions` lists the `outsideProject` declaration in its+ command doc fields and its checklist.+- Consumer docs (`cli`) describe the doors, which release answers a folder,+ what commands do outside a project, the per-user release cache, the update+ check and its notices, and how the computer-level text is installed and+ turned off.+- The response fields this record adds are additive (`spec:AST-017` FR13). A+ new refusal, a moved error code, or a changed exit status outside a project+ is classified under `spec:AST-017` before it ships.++This specification change alters no runtime behavior or published package and+needs no Changeset.++## Verification++| Contract | Verification | Representative states | Mutation or failure expectation |+| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| FR1 | Door conformance: every command example, run through each door; host entry tests | a project on the current minor and one on the previous minor; an empty folder; text and JSON; a second call in one process; a door source beside project and integration sources | A door's exit status, output, or file changes differ beyond FR5's command names and the FR5 and FR6 lines, a door's input reaches the CLI any way but the host entry, a second call in one process runs, or a door's source is called out of order or named as an integration's |+| FR2 | Release check: every page template scaffolded through a door into a project on the previous release, then typechecked; hand-off probes | a project with its own CLI; a project whose CLI and Core differ, both ways; a project with Core only; a workspace member with its own Core under a root CLI; a fresh clone with a lockfile and with only a declared range; an upgrade with a project CLI older than its Core; a declined project CLI, with its release and with it unavailable (the starting copy answers, announced, naming the reason); an unavailable release | A template fails where the matched release passes, a release other than the one equal to the project's Core answers, project configuration runs in another copy, or another release answers in place of an unavailable one |+| FR3 | Empty-folder run of every command example | each command that needs Core; `doctor`, `swizzle`, and `upgrade`; a folder with no `package.json`; a home folder; a copy with no Core | A command that needs Core fails beside a carried Core, a project check reads it, or output gives a project step |+| FR4 | Declaration check over every command doc, plus the empty-folder run compared with each declaration | `same`, `refuse`, and `own`; a command group; a command without a value; a released refusal code | A command lacks a value, a `refuse` writes or uses an unlisted code, or a command's behavior differs from its value |+| FR5 | Printed-command check: each command the CLI prints or writes, run from the same folder through the door that printed it; a picker check over every surface that prints a command; a check of shipped text; result-field tests | each door; `project`, `matched`, and `carried`; no declaration, one integration's command, two that agree, two that disagree, and a malformed one; hints, errors, `doctor` fixes, help, docs moves, agent text, and the setup reminder; text and JSON | A printed command reaches another door or release, a surface prints a name the picker did not choose, the picker's order changes, a disagreement prints either integration's command or `doctor` stays silent, a malformed declaration withdraws its integration, shipped text writes a CLI command any way but bare, JSON carries a picked name, `meta.answeredBy` is missing or wrong, or the line prints for the project's own CLI |+| FR6 | Update check tests | first run; within and after 24 hours; `CI` set to yes and to `false`; `NO_UPDATE_NOTIFIER` set; an unreachable registry; ten runs at once; a requested version; a package runner's copy; inside a project | A check runs in the first day, twice in a day, with `CI` or `NO_UPDATE_NOTIFIER` set, or for a fetched copy; a command waits for it or its output changes; or a check installs or switches a release |+| FR7 | File-system comparison before and after each command in the empty-folder run and in projects | each command that writes; absolute, traversal, and symlinked paths; a home folder | A file lands outside the named places, or a refusal writes first |+| FR8 | Release build, drift checks, a starter build in CI, and computer-level text tests | the official list; the agent text for each door; each starter; the global copy's first run and a switch; `--agent` lists; an opt-out; a file a person edited; a file without markers; a link in a file's place; a strict YAML parse of every skill file | A committed copy drifts, a global asset is fetched at run time, the computer-level text names a version, a starter fails to scaffold, install, or build, the global copy writes after an opt-out or into an edited file, a command waits for the text, or a skill's frontmatter does not parse |+| FR9 | Hand-off probes: every command example run through each copy in each folder kind, compared with the release FR2 names run directly in that folder | the CLI package installed for the computer on an older and on a newer release than the project's CLI, run directly and run by a package runner in place of a fetch; a package runner's copy, unversioned and with a version requested inside a project, for a read and for `upgrade`; a project with Core but no CLI, through a package runner that fetches the newest release; a package with no Astryx inside a project, which the package runner takes for the project; a project CLI that predates the hand-off and one that hands off itself; a declined project CLI; a project CLI that cannot start; a non-zero exit; piped standard input; outside a project; text and JSON | A release other than the one FR2 names answers in a project, outside the declined case; a project CLI that differs from its Core answers; a requested version answers inside a project; a run is handed off twice or returns to a copy it left; arguments, folder, streams, or exit status differ from a direct run of the project's CLI; outside a project, a release answers that FR3 and FR6 do not name; or the line is missing, prints twice, prints in JSON mode, or prints for a run the project's own CLI answers directly |+| FR10 | Notice tests | the global copy behind, for npm, pnpm, Yarn, Bun, and Volta installs; a newest release that needs a newer Node; a project behind, with and without its own CLI; an old `astryx` first on the search path; two runs in one day and a run the next day; a failed command; JSON mode; `CI`; `NO_UPDATE_NOTIFIER`; standard error not a terminal; a prerelease | A notice prints in JSON mode, after a failure, twice in a day, with `CI` or `NO_UPDATE_NOTIFIER` set, or before the command's output; it names another package manager's command; or `doctor` omits it |+| FR11 | One test per row of the global and project table, with packed CLI copies in each install layout | every row of the table | A row's answer, line, or test differs from the table, or a row has no test |+| FR12 | Computer-level integration tests and table rows G35–G43 | npm and pnpm global folders; a door's package set; a runner's temporary install; the release cache; outside a project; inside one with and without the same integration; an incompatible peer range; a manifest that fails | A computer-level integration contributes inside a project, is missing outside one, loads beside the project's copy, loads with an excluded peer range, or `discover` and `doctor` omit it |++## Decision log++### DEC-1 — One release answers each folder++**Reference:** `spec:AST-081/DEC-1`+**Decider:** `josephfarina`, `2026-10-19`++Two releases in one run write code that fails without an error: one release's+templates and component docs use props another release's Core does not have,+and the same command can import a theme in one release and copy its source in+another, both exiting 0. So one release answers everything in a project: the+project's own CLI, or without one the release equal to its Core (DEC-10). When+that release cannot be obtained, as offline or behind a registry without it,+the copy that started the run answers, as before global mode, and says so on+one line and in `meta.answeredBy`. Failing those runs would+break commands that worked before global mode, and the warning keeps the+mismatch visible; falling back while the matched release can be obtained would+bring the silent mix back, so it never happens.++Rejected: the newest release answering everywhere, which writes code an older+project's Core rejects; failing every run whose matched release cannot be+obtained, which breaks commands that worked before global mode; and falling+back to any other release, or without saying so.++### DEC-2 — Outside a project, answer as a new project would++**Reference:** `spec:AST-081/DEC-2`+**Decider:** `josephfarina`, `2026-10-19`++An agent with no project files still needs Core's components and docs, and a+new project on the release it runs is what it would create. The carried Core+serves only commands that do not judge or change a project, so an empty folder+never passes a project check or receives a component copy whose packages+nobody installed.++Rejected: refusing every command that needs Core outside a project, which+leaves an agent without project files unable to learn Core.++### DEC-3 — Each command declares same, refuse, or own++**Reference:** `spec:AST-081/DEC-3`+**Decider:** `josephfarina`, `2026-10-19`++A declaration in each command doc, published in the manifest, tells a door and+an agent before a run whether a command works outside a project, and lets a+check prove the behavior matches. One shared refusal code lets an agent branch+on "open or start a project first" without learning each command's failure.++Rejected: a project, global, or both scope, which cannot express a command that+does a different job outside a project or has modes of each kind.++### DEC-4 — Who answered is data, and printed commands return through their door++**Reference:** `spec:AST-081/DEC-4`+**Decider:** `josephfarina`, `2026-10-19`++An agent comparing two reads needs to know whether one release gave both; a+field in `meta` tells it without changing an existing field or the envelope. A+printed command that names another door or an unpinned package starts a+different release than the one that printed it.++Rejected: a new top-level envelope field, which changes the envelope every+consumer reads.++### DEC-5 — No door changes a project's versions++**Reference:** `spec:AST-081/DEC-5`+**Decider:** `josephfarina`, `2026-10-19`++A project's versions belong to its owner, so no door installs into a project;+FR10 tells the owner instead, with the exact commands, and `doctor` reports+what is newer.++Rejected: updating a project, or installing into one, from any door.++### DEC-6 — Anything global ships inside the release++**Reference:** `spec:AST-081/DEC-6`+**Decider:** `josephfarina`, `2026-10-19`++A list, a starter, or an agent text fetched at run time can disagree with the+release that reads it, and fails offline. Generated when the release is built,+it is exactly as current as the CLI that uses it.++Rejected: fetching global assets at run time.++### DEC-7 — Doors start the CLI through one entry, and their sources are their own++**Reference:** `spec:AST-081/DEC-7`+**Decider:** `josephfarina`, `2026-10-19`++A door's inputs cannot travel by flag or environment variable, and a call takes+over the process it runs in, so every door uses one documented programmatic+entry, once per process. A catalog a door serves is the door's source, named as+the door's and read after the integrations' sources, so a reader can tell which+catalog listed a package.++Rejected: replacing an integration's discover source under that integration's+name, which reports the door's catalog as the integration's own.++### DEC-8 — One picker names every printed command, and an integration's command comes first++**Reference:** `spec:AST-081/DEC-8`+**Decider:** `josephfarina`, `2026-10-19`++An integration that gives its users a command of its own knows how they reach+the CLI better than a guess from the package manager, and a door's name covers+only the runs that start in that door, so the picker tries the integration's+command, then the door's name, then the package manager's. When integrations+disagree, neither is right for every user of the project, so the picker uses+the package manager's name and `doctor` says why. Text written with a bare+`astryx` that takes the picked name when shown lets one doc serve every door+and stay correct when the door changes, and JSON keeps the one spelling a+program can rely on.++Rejected: settling a disagreement by integration order, which lets load order+choose the command a project's users are told to run.++### DEC-9 — Every copy hands off, so any install route reaches the project's release++**Reference:** `spec:AST-081/DEC-9`+**Decider:** `josephfarina`, `2026-10-19`++The CLI package itself is the common install, for the computer or through a+package runner, and a copy installed for the computer is also what a package+runner runs in place of a fetch. If only a separate launcher package handed a+project's run on, those routes would answer with their own release and bring+back the mix DEC-1 rejects, so the CLI package itself is the global install and+needs no launcher. A hand-off built into every copy makes the+project's pinned release answer wherever a run starts, a typed version+included, and leaves a run outside a project with the copy its caller chose.+One standard-error line keeps a hand-off visible without changing+machine-readable output.++Rejected: global mode only through a separate launcher package, which leaves+the common install routes answering with their own release inside projects and+gives people two packages to choose between.++### DEC-10 — Until the next minor release, a project is answered as it was before global mode++**Reference:** `spec:AST-081/DEC-10`+**Decider:** `josephfarina`, `2026-10-20`++A project's CLI and Core drift apart after a partial upgrade, and in a+workspace an app can install an older Core than the root's CLI. The CLI's+release writes the templates, docs, and agent text, and the Core's release+supplies the components, so a mismatched pair can write code that does not+compile. The Core is what the project's code runs against, so the release equal+to it should answer. But a project that installs its own CLI has always been+answered by that CLI, and one with only Core by whichever copy the person+started; having another release answer either changes what an in-range install+does, which `spec:AST-017` FR12 does not allow under a nonbreaking label. So in+this release the project's own CLI answers whatever its version, a project with+no CLI of its own is answered by the copy that started the run with a daily+hint, `doctor` warns about either mismatch and names the command that aligns+them, and the matched release answers only a project whose own CLI cannot+start. The release equal to the Core answering over a differing project CLI,+and answering a project with only Core, are a breaking change for the next+minor release.++Compatibility with released routes: a project's own CLI run directly, as with+`npx astryx` or a package script, answers as before, and so does a project with+no CLI of its own. The one route that changes is a copy other than the+project's own CLI started inside a project that installs its own CLI of another+release: a global install, `npx @astryxdesign/cli@<version>`, or another package+runner's fetch. Before global mode it answered with its own release and the+project's Core; now it hands the run to the project's CLI (FR9), so it answers+exactly what the project's own command does, and a command newer than the+project's CLI is not reachable that way inside the project. The released docs+name the project's own command inside a project and install the new CLI before+`astryx upgrade`, so no documented route changes, and the JSON shape is the+same; the commands that act on the computer (FR9) still answer from the copy+that started the run.++Rejected for this release: the release equal to the Core answering over the+project's own CLI, or answering a project with only Core, which changes what an+existing install answers in a patch release; and leaving a mismatch silent.++### DEC-11 — The global copy answers with its own installed release++**Reference:** `spec:AST-081/DEC-11`+**Decider:** `josephfarina`, `2026-10-19`++What answers outside a project is what the person installed, so the version+they see is the version the package manager reports, and an upgrade is a step+they take with the tool that installed it (DEC-16). The per-user cache holds+only the releases a project's run needs.++Rejected: answering from releases kept in the per-user cache and switching to+the newest in the background, which changes what answers without the+person's step; and replacing the installed copy, which writes outside FR7's+places and can need administrator rights.++### DEC-12 — The computer-level agent text is one skill file, linked where agents look++**Reference:** `spec:AST-081/DEC-12`+**Decider:** `josephfarina`, `2026-10-19`++A skill loads only when an agent uses Astryx, so it costs nothing in the+sessions that never touch it. One file in the shared skills folder reaches+most agent tools; linking its folder into each folder a tool reads alone+reaches the rest with the same bytes, so a refresh is one write and no copy+drifts. The only copy is for a tool whose scanner skips links.++Rejected: a copy of the file per agent tool, which multiplies writes and lets+copies drift; letting a person pick agents, which adds an option for what+existence of a tool's folder already says; and one always-on instruction file+per agent, which loads in every session and reaches fewer agents.++### DEC-13 — The global copy installs the computer-level text itself, in the background++**Reference:** `spec:AST-081/DEC-13`+**Decider:** `josephfarina`, `2026-10-19`++The text has to be present wherever the CLI is installed for the computer, and+stay matched to the release that answers. A package's install scripts do not run+reliably: several package managers block them by default, and any install can+skip them, so the text would be present on some computers and missing on others+with nothing to say why. The global copy runs on every computer it is installed+on, so it writes the text on its first run and on the first run after it is+upgraded, from a detached background step that no command waits for. Choices+live in a documented settings file, so a person's opt-out survives every update,+and the links the CLI made are recorded there, so removal is exact. A hash in+the markers tells a person's edit from an older rendering, so an edit is never+lost.++Rejected: a package install script, which several package managers block by+default; writing in the foreground of every command, which slows commands and+makes output depend on the computer; and an environment variable or option to+turn it off, which a person has to repeat everywhere and an agent cannot see.++### DEC-14 — Notices name the upgrade, at most once a day, even without a terminal++**Reference:** `spec:AST-081/DEC-14`+**Decider:** `josephfarina`, `2026-10-19`++A copy or a project that falls behind writes code against a release nobody+chose, and nothing else tells its owner. A notice that names both versions+and the exact command turns that into one step. It prints after the command,+so the command's own output comes first; at most once a day per notice, so a+person or an agent running many commands sees it once; never in+machine-readable output, so programs read the same fields; and only after a+check, so a fresh home stays quiet about a newer release. A command that+predates the hand-off answers every folder with its own release, so its+notice needs no check. Unlike `gh`, which prints only to a terminal, a notice+prints when standard error is not one, because agents, the CLI's main+callers, run it without a terminal and would otherwise never learn of a newer+release; `CI` and `NO_UPDATE_NOTIFIER` still silence it.++Rejected: a line on every run, which agents learn to ignore; printing only to+a terminal, which no agent sees; staying silent, which leaves copies and+projects behind indefinitely; and updating a project automatically, which+changes a project's versions without its owner.++### DEC-15 — Every meeting of global and project copies is a table row with a test++**Reference:** `spec:AST-081/DEC-15`+**Decider:** `josephfarina`, `2026-10-19`++Global and project copies meet in many ways, from version managers to links+and shared caches, and each one is easy to get wrong in only one of them. One+table, one row per case, and one test per row lets a contributor see who+answers before changing the hand-off, and makes a missing case visible. A+copy that predates these rules cannot be changed, so it is reported and its+replacement named, never worked around.++Rejected: describing the cases only in prose, which hides the case nobody+listed.++### DEC-16 — Notify, never self-update, as `gh` and the Vercel CLI do++**Reference:** `spec:AST-081/DEC-16`+**Decider:** `josephfarina`, `2026-10-19`++The global copy follows the standard that command-line tools installed through+a package manager share: `gh` checks its newest release once a day and, after+a command, prints `A new release of gh is available` with the upgrade command;+the Vercel CLI and the update-notifier package check once a day in a detached+process, name the install command of the package manager that installed the+tool, and stay silent in continuous integration and under+`NO_UPDATE_NOTIFIER`. Following it means the release that answers is always+the one the person installed, upgrades happen through the package manager's+own installation and permissions, and a person who knows one of these tools+knows this one.++Rejected: installing newer releases into the per-user cache and switching to+them in the background, which kept the CLI current without a step but changed+what answers without the person choosing it; the standard was chosen instead.++### DEC-17 — Integrations installed for the computer apply outside projects only++**Reference:** `spec:AST-081/DEC-17`+**Decider:** `josephfarina`, `2026-10-19`++Integrations change what the CLI answers, so a person who installs one beside+the CLI installed for the computer, or a tool that installs one with the CLI,+expects it to apply wherever no project decides: an agent outside any project+then learns that integration's components and docs too. Inside a project, the+project decides: its output must match what it installs, so a component, a+template, or an import from a package it does not install would be code that+fails to build. Listing the integration as available, with the project's+install command, keeps it findable without changing the project's answers.+Reading the install root itself, instead of a host input, gives every install+route the same rule.++Rejected: computer-level integrations applying inside projects too, which+makes a project's answers depend on the computer and prints imports of+packages the project does not install; and requiring a host entry input for+them, which leaves a global install without them.++## Open questions++None.