space-architect 1.3.0 → 2.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db24aa20a68fdf981176f7e51a46794a4fc2ec5cef9765c33de5832f0a314a9e
-  data.tar.gz: 8912085239c76c1228e01d8986d789ba0fde42b4517459830c1f08cdb6e0fcfc
+  metadata.gz: 3022f9e726e74aa3edeca3004af6e3af1a7872bd709fb0da75fbeee5fcf33d30
+  data.tar.gz: f3f2aef35926a99ba14209c550fb0533da777561df7348d4e0bfce19ee240f86
 SHA512:
-  metadata.gz: 06a4e3382403542421679272136d6c1f6a99ac5dece354b5175f5d895b1afb9cce902f9e11ea2cf64c940dd4a00f11d3dfa7390a0941f387ae4a28f47cdbc3fb
-  data.tar.gz: 73c71c080f640540c4cfb57f347f12eae5a2486c45a373a525c44dc35ea54edf7b43ee415d979352f6569406f0f261e8d4a601af869eae5bd9f9055df02d9807
+  metadata.gz: 480cd0f4dbb96653f6c4db809755e8968cf4bb96311472dde9a2e5172d22526589d20ca522bd028180eac6d2c772e41e80236474da9f8ab2b4597128227be21b
+  data.tar.gz: 7089e119fe3a0b7bee92facd78dd691ddcf84daae4dc783dda80c2513042ab1d1e1767b5afd099012dd4029c9e0a126c8ea3f7c5b48fe3d056bc8a7b7c7a03a8

data/CHANGELOG.md

@@ -0,0 +1,103 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.0.0] - 2026-06-27
+
+Re-architects the single `architect` gem into three composable binaries —
+**`space` · `architect` · `src`** — over clean `Space::Core` / `Space::Architect`
+/ `Space::Src` library seams. End-user CLI behaviour is preserved byte-for-byte
+except where called out under **Changed** below.
+
+### Added
+
+- **`src` — standalone evergreen-engine binary** (`exe/src`). `repo`, `org`,
+  `sync`, `status`, `config`, `daemon`, and `clone`, plus single-token fuzzy
+  navigation (`src <query>` resolves to a repo and honours the `cd` contract)
+  and native fish shell integration with completions. Previously this engine was
+  reachable only as `architect src …`; it is now a first-class binary in its own
+  right (and still forwarded by `architect src …`).
+- **`architect research dispatch | status | wait`** — first-class parallel,
+  read-only research lanes. Detached `claude -p` researchers (no Edit/Write/Bash)
+  run in the background; a socketry/async fiber mux tails each lane's `run.jsonl`
+  and extracts its report. The architect verifies claims and writes Grounds.
+- **`architect dispatch --detach`** — detached builder launch that returns
+  immediately with a PID and survives the harness wall-clock reap; poll the
+  lane's report for completion.
+
+### Changed
+
+- **BREAKING — three binaries over clean seams.** `space` now runs on
+  `Space::Core` alone (`exe/space`); `architect` forwards `space …` / `src …` to
+  their surfaces; `src` is its own executable (`exe/src`). The gem now installs
+  three executables (`architect`, `space`, `src`) where 1.3.0 installed two.
+- **BREAKING — Ruby namespace overhaul (library embedders).** The single
+  `SpaceArchitect::*` module is retired and split into `Space::Core::*`
+  (foundation: config, state, XDG, terminal, git/mise clients, space store),
+  `Space::Architect::*` (mission, harness, dispatch, research), and
+  `Space::Src::*` (the evergreen engine). Update any `require`s and constant
+  references. The CLI surface is unaffected.
+- **BREAKING — `repo-tender` absorbed into `space-src`.** The vendored
+  `repo-tender` engine is gone; its functionality now ships as `Space::Src`.
+  State migrates automatically from `$XDG_STATE_HOME/repo-tender/` to
+  `$XDG_STATE_HOME/space-src/` on first run (data-preserving).
+- **BREAKING — `space new` takes repeatable `-r` flags.** Repos are now passed
+  as `space new "My Space" -r org/repo -r example/alpha` instead of as positional
+  arguments after the title. Repeated `-r` accumulate; the comma form still works.
+- **Colourful global help** for `space` and `architect` (`--help` listing), with
+  global colour options (`--color` / `--colors`) inherited by every command via a
+  shared `BaseCommand`. The `src` binary keeps its own `--plain` / `--json`
+  output system.
+- `space --version` now reports the space-surface (`Space::Core`) version
+  independently of the architect mission tooling.
+
+### Internal
+
+- `Space::Core` carved out as a standalone, leak-free foundation (no
+  `SpaceArchitect` references); behaviour preserved byte-for-byte across the
+  carve, the module rename, and the binary split.
+- CI: `softprops/action-gh-release` bumped to v3 (Node 24 runtime).
+- Test suite: 762 runs, 0 failures.
+
+## [1.3.0] - 2026-06-25
+
+### Added
+
+- `architect install-skills` — install the bundled skills (architect,
+  architect-research, architect-vocabulary) for claude / codex / opencode / pi,
+  globally or per-project, with `--dry-run` and `--force`.
+- `architect-vocabulary` skill — a self-contained glossary of the Architect
+  system, loadable without running the loop.
+
+### Fixed
+
+- Broke a circular `require` in the vendored `pristine/cli`; silenced stray git
+  worktree output in the test suite.
+
+## [1.2.0] - 2026-06-24
+
+### Added
+
+- §-anchored mission **BRIEF** (`architect brief new`) cited as `BRIEF §N` across
+  iterations, and persistence absorbed into the CLI: `architect section`,
+  `evidence`, `merge`, `integrate`, and `gate` (the architect authors content;
+  the CLI owns the commit). `architect freeze` now prints the frozen Acceptance
+  Criteria back; `worktree add --touch` records a lane's touch set.
+
+### Changed
+
+- Reduced Architect Loop ceremony; restored the § citation anchor.
+
+## [1.1.0] - 2026-06-21
+
+- First tagged release: the Architect Loop CLI — spaces, missions, iterations,
+  lanes, worktrees, and headless `claude -p` dispatch, with variant sets and the
+  claude-code and opencode harnesses.
+
+[2.0.0]: https://github.com/jetpks/space-architect/compare/v1.3.0...v2.0.0
+[1.3.0]: https://github.com/jetpks/space-architect/compare/v1.2.0...v1.3.0
+[1.2.0]: https://github.com/jetpks/space-architect/compare/v1.1.0...v1.2.0
+[1.1.0]: https://github.com/jetpks/space-architect/releases/tag/v1.1.0

data/README.md

@@ -4,10 +4,22 @@
 
 > **Task-scoped workspaces that double as Architect Loop missions — for humans and their agents!** ✨🛰️
 
-`space-architect` is a Ruby CLI for creating and managing **spaces** — task-scoped
-project workspaces that hold repos, notes, and artifacts under one obvious
-filesystem root — fused with the **Architect Loop**: a structured judgment-and-build
-cycle for you and a fleet of headless AI builders. 🌌
+`space-architect` is a Ruby toolkit for **spaces** — task-scoped project
+workspaces that hold repos, notes, and artifacts under one obvious filesystem
+root — fused with the **Architect Loop**: a structured judgment-and-build cycle
+for you and a fleet of headless AI builders. 🌌
+
+The gem ships **three composable binaries** over clean library seams:
+
+| Binary | What it does | Library |
+|--------|--------------|---------|
+| **`space`** 🪐 | Create and manage task-scoped workspaces | `Space::Core` |
+| **`architect`** 🏗️ | Run the Architect Loop — judgment + headless builders | `Space::Architect` |
+| **`src`** 🌲 | Tend evergreen repo checkouts for copy-on-write provisioning | `Space::Src` |
+
+Each is a first-class executable. `architect` also forwards `architect space …`
+and `architect src …` to the other two, so a mission can drive everything from
+one command when that's handier. 🎀
 
 ## What's a space? 🪐
 
@@ -15,19 +27,20 @@ A space is just a regular directory with a tiny YAML identity file and room for
 everything a task needs:
 
 ```text
-~/src/spaces/20260531-name-of-space/
+~/architect/spaces/20260531-name-of-space/
   space.yaml        # identity: id, title, status, repos, notes, tags
   README.md
   repos/            # cloned (or copy-on-write'd) repositories
   notes/            # scratch, prompts, logs
-  architecture/     # iteration files: I<NN>-<name>.md + ARCHITECT.md index
+  architecture/     # iteration files: I<NN>-<name>.md + ARCHITECT.md index + BRIEF.md
   build/            # lane worktrees + scratch (build/<id>-<lane>/)
   tmp/              # workspace-local temp — use this instead of /tmp
 ```
 
-Run a command from anywhere inside a space and it just works — `architect` walks
-up from `$PWD` until it finds the nearest `space.yaml`. No "current space" state to
-get out of sync; where you *are* is the space you mean. 🧭
+Run a command from anywhere inside a space and it just works — `space` and
+`architect` walk up from `$PWD` until they find the nearest `space.yaml`. No
+"current space" state to get out of sync; where you *are* is the space you
+mean. 🧭
 
 ## Installation 📦
 
@@ -37,8 +50,6 @@ Add it to your `Gemfile`:
 gem "space-architect"
 ```
 
-Then:
-
 ```bash
 bundle install
 ```
@@ -49,225 +60,307 @@ Or grab it yourself:
 gem install space-architect
 ```
 
-The primary executable is `architect`. The gem is `space-architect`. 🎀
-A `space` shim is also installed and forwards all arguments to `architect space …`
-for convenience.
-
-## Quick Start 🎀
+The gem is `space-architect`; it installs three executables — `space`,
+`architect`, and `src`. 🎀
 
-**Space management:**
+## Quick start 🎀
 
 ```sh
-architect space init                              # create XDG config + state files
-architect space new "Name of Space"              # blast off a new space 🚀
-architect space new "Name of Space" org/repo …  # with repos cloned in (variadic)
-architect space list                             # see all your spaces
-architect space show                             # show the space you're standing in
-architect space status done                      # mark the current mission complete
+# Spaces
+space init                                        # create XDG config + state files
+space new "Name of Space"                         # blast off a new space 🚀
+space new "Name of Space" -r org/repo -r org/lib  # …with repos cloned in (repeat -r)
+space list                                        # see all your spaces
+space show                                        # show the space you're standing in
+
+# Evergreen checkouts (copy-on-write sources for fast provisioning)
+src repo add github.com/example-org/example-app     # tend it 🌲
+src sync                                            # one sync pass
+src status                                          # per-repo evergreen status
+
+# Architect Loop (run from inside a space)
+architect install-skills                          # install agent skills (once per machine)
+architect init                                    # scaffold ARCHITECT.md + architecture/
+architect new my-feature                          # scaffold the next iteration file
+architect freeze my-feature                       # lock the Acceptance Criteria ❄️
+architect dispatch my-feature lane-a              # send a headless builder to work
 ```
 
-**Architect Loop (run from inside a space):**
+## `space` — task-scoped workspaces 🌌
 
 ```sh
-architect install-skills                          # install skills for your harness (once per machine)
-architect init                                   # scaffold ARCHITECT.md + architecture/
-architect new <iteration>                        # scaffold next iteration file
-architect dispatch <iteration> <lane>            # dispatch a builder for a lane
-architect status                                 # show mission state (read-only)
-architect freeze <iteration>                     # freeze Acceptance Criteria
-architect verify <iteration>                     # post-flight mechanical checks
+space init
+space new "Name of Space"
+space new "Name of Space" -r org/repo -r example-tools/alpha -r example-tools/beta
+space list                                   # alias: space ls
+space show 20260531-name-of-space
+space path 20260531-name-of-space
+space current                                # based on $PWD
+space show                                   # based on $PWD
+space status done                            # based on $PWD
+space status 20260531-name-of-space done
+space config set default_provider github.com
+space config set default_organization example-org
+space repo add example-app                   # github.com/example-org/example-app
+space repo add example-tools/alpha example-tools/beta
+space repo add gitlab.com/example-org/api
+space repo resolve example-app example-tools/async
+space repo ls                                # alias: space repos ls
+space use 20260531-name-of-space             # records recent state, prints the path
+space ls --color=always                      # auto | always | never (--colors also accepted)
 ```
 
-`architect install-skills` installs the bundled `architect`, `architect-research`,
-and `architect-vocabulary` skills for a harness. (`architect-vocabulary` loads the
-system's terms and a short orientation when you're in a space but don't want to run
-the loop — see [The Architect Loop](#the-architect-loop-).) Default is `claude`
-(`~/.claude/skills/`); use `--provider
-opencode|codex|pi` for other harnesses, and `--project` to install into the current
-directory instead of globally. See the [command reference](docs/reference.md) for details.
+Repos are passed with a repeatable `-r` flag (`-r org/repo -r org/lib`); the
+comma form (`-r a,b`) works too. Space ids are date-prefixed
+(`20260531-name-of-space`) so they sort naturally, and duplicate names on the
+same day get a counter (`…-name-of-space-2`). 📅
+
+Everything `space` does is also reachable as `architect space …` from within a
+mission.
 
-## Usage 🛰️
+## `src` — the evergreen engine 🌲
+
+`src` keeps local clones under `<src_dir>/<host>/<owner>/<repo>` (default
+`~/architect/src/…`) clean, on their default branch, and freshly fetched — so
+spaces can provision repos by **copy-on-write** instead of cloning over the
+network.
+
+```sh
+src repo add github.com/example-org/example-app     # track + tend a repo
+src org add github.com/example-org                  # track a whole org
+src sync                                            # run one sync pass (--repo to scope)
+src status                                          # per-repo evergreen status table
+src clone example-app                               # APFS copy-on-write into $PWD
+src daemon install                                  # per-user launchd agent for background sync
+```
+
+When `space repo add` finds a matching evergreen checkout, it copy-on-writes
+from it instead of hitting the network — instant provisioning. ⚡ The two
+surfaces share one layout by design, so they line up with zero configuration:
 
 ```sh
-architect space init
-architect space new "Name of Space"
-architect space new "Name of Space" org/repo example-tools/alpha example-tools/beta
-architect space list
-architect space show 20260531-name-of-space
-architect space path 20260531-name-of-space
-architect space current                      # based on $PWD
-architect space show                         # based on $PWD
-architect space status done                  # based on $PWD
-architect space status 20260531-name-of-space done
-architect space config set default_provider github.com
-architect space config set default_organization example-org
-architect space repo add example-app         # github.com/example-org/example-app
-architect space repo add example-tools/alpha example-tools/beta
-architect space repo add gitlab.com/example-org/api
-architect space repo resolve example-app example-tools/async
-architect space repo ls
-architect space use 20260531-name-of-space   # records recent state and prints the path
-architect space ls --color=always            # auto, always, or never; --colors is also accepted
+src repo add github.com/example-org/example-app   # tend it: keep it evergreen 🌲
+space repo add example-app                          # copies it instantly ⚡
 ```
 
-Space ids are date-prefixed (`20260531-name-of-space`) so they sort naturally,
-and duplicate names on the same day get a counter (`...-name-of-space-2`). 📅
+`src` has its own `--plain` / `--json` output modes for scripting, and its own
+fish integration (`src shell fish install`).
 
-## The Architect Loop 🏗️
+## `architect` — the Architect Loop 🏗️
 
-Space Architect ships a structured build cycle for you and headless AI builders
-called the **Architect Loop**. Each loop lives inside a space as a *mission*.
+The **Architect Loop** is a structured build cycle for you and headless AI
+builders. Each loop lives inside a space as a *mission*.
 
 **Roles:**
 
-- **Architect** — you (or Claude Opus 4.8 in judgment mode): arbitrates disagreements,
-  writes and freezes iteration files, calls kill/continue, merges builder output.
-- **Builder** — Claude Sonnet 4.6 run headless via `architect dispatch`; reads the
-  iteration's Builder Prompt from `architecture/`, does the work, writes its report
-  to `build/<id>-<lane>/`.
+- **Architect** — you (or Claude Opus 4.8 in judgment mode): arbitrates
+  disagreements, writes and freezes iteration files, calls kill/continue, merges
+  builder output. Never writes implementation code.
+- **Builder** — Claude Sonnet 4.6 run headless via `architect dispatch`, one per
+  lane in its own git worktree: reads the iteration's Builder Prompt, does the
+  work, writes raw evidence to `build/<id>-<lane>/report.md`. Never grades its
+  own work; never edits `architecture/`.
 
 **Filesystem layout:**
 
 ```text
 architecture/
   ARCHITECT.md              # cross-iteration index; mission-wide state
-  I01-<iteration>.md        # one file per iteration
-  I02-<iteration>.md
+  BRIEF.md                  # durable §-numbered mission contract (optional)
+  I01-<iteration>.md        # one self-contained file per iteration
 build/
   I01-<iteration>-<lane>/   # lane worktree + scratch per dispatch
     run.jsonl               # streamed builder output
-    report.md               # builder report (transcribed to iteration file verbatim)
+    report.md               # builder report (transcribed into the iteration file verbatim)
 ```
 
-**Iteration file anatomy** (in `architecture/I<NN>-<name>.md`):
+**Iteration file anatomy** — one file, grown section by section. You author the
+*content*; the CLI owns the *persistence* (each command writes the section,
+commits it with the canonical message, and prints back what changed):
 
-| Section | Who writes it | When |
-|---------|--------------|------|
-| `## Grounds` | Architect | Before dispatch — research, PRD, decisions |
-| `## Specification` | Architect | Before dispatch — full delegation contract |
-| `## Acceptance Criteria` | Architect | Before `architect freeze` — frozen, read-only after |
-| `## Builder Prompt` | Architect | Records the exact prompt dispatched |
-| `## Builder Report` | Architect | Transcribed verbatim from `build/…/report.md` |
-| `## Verdict` | Architect | After reviewing evidence — KILL / CONTINUE |
+| Section | Holds | How you persist it |
+|---------|-------|--------------------|
+| `## Grounds` | why — research / brief distilled (optional) | `architect section <it> grounds --from <f>` |
+| `## Specification` | what/how — the full delegation contract | `architect section <it> specification --from <f>` |
+| `## Acceptance Criteria` | proof — exact gate commands + thresholds | `architect freeze <it>` ❄️ |
+| `## Builder Prompt` | the exact lane-prompt(s) dispatched | `architect section <it> prompt --append --lane <l> --from <f>` |
+| `## Builder Report` | raw evidence, transcribed verbatim | `architect evidence <it> --lane <l>` |
+| `## Verdict` | rulings + per-AC PASS/FAIL + KILL/CONTINUE | `architect section <it> verdict --from <f>` |
 
-**Acceptance Criteria freeze before results** — `architect freeze <iteration>` commits
-the frozen sections and records `freeze_sha`; any change to Grounds, Specification,
-or Acceptance Criteria after that point is an automatic iteration FAIL. The builder
-never edits the iteration file.
+**The freeze ❄️** — `architect freeze <iteration>` commits the frozen region
+(Grounds / Specification / Acceptance Criteria), records the `freeze_sha`, and
+prints the frozen Acceptance Criteria back. Any change to those sections
+afterward is an automatic iteration FAIL. The builder never edits the iteration
+file.
 
-**Typical loop session:**
+**Command surface:**
 
 ```sh
-# From inside your space:
-architect init                                   # first time: scaffold ARCHITECT.md
-architect new my-feature                         # scaffold architecture/I01-my-feature.md
-# … write Grounds + Specification + Acceptance Criteria …
-architect freeze my-feature                      # lock it
-architect dispatch my-feature lane-A             # send builder to work
-# … builder runs, writes build/I01-my-feature-lane-A/report.md …
+architect init                              # scaffold ARCHITECT.md + the space.yaml architect: block
+architect brief new                         # scaffold the durable mission BRIEF.md
+architect new <iteration>                   # scaffold architecture/I<NN>-<iteration>.md
+architect section <it> <section> --from <f> # write + commit a section
+architect freeze <iteration>                # freeze the Acceptance Criteria ❄️
+architect worktree add <repo> <it> <lane>   # isolated worktree per lane (2–4 lanes)
+architect dispatch <it> <lane>              # dispatch a builder (add --detach to survive long runs)
+architect verify <iteration>                # post-flight mechanical checks (reports only)
+architect evidence <it> --lane <lane>       # transcribe the builder's report verbatim
+architect gate <iteration>                  # run the frozen gate commands, stream raw output
+architect merge <it> <lane>                 # integrate ONE judged-passing lane (--no-ff)
+architect integrate <it> --lanes a,b        # integrate a set of passing lanes, in order
+architect status                            # mission state (read-only)
+architect variant add|compare|promote …     # competing (harness, model) lanes over one frozen spec
+architect research dispatch|status|wait …   # parallel read-only research lanes (see below)
+```
+
+A typical session:
+
+```sh
+architect init                                   # first time
+architect new my-feature                         # scaffold I01-my-feature.md
+architect section my-feature specification --from spec.md
+architect freeze my-feature                      # lock it ❄️
+architect dispatch my-feature lane-a --detach    # send a builder; poll the report
 architect verify my-feature                      # mechanical post-flight checks
-architect status                                 # review mission state
-# … architect reads evidence and writes Verdict …
+architect evidence my-feature --lane lane-a      # transcribe raw evidence
+architect gate my-feature                        # run the frozen gates yourself
+# … read the diff against the spec, then write the Verdict …
 ```
 
+### Streaming builder output 📡
+
+`architect dispatch` can push the builder's stream-json to an ingest server for
+live viewing:
+
+```sh
+# Push to an already-created run (you supply the full ingest URL):
+architect dispatch my-feature lane-a \
+  --push-url   $HOST/runs/<id>/ingest \
+  --push-token $INGEST_TOKEN
+
+# Create a run and push in one step (requires --push-token = server's INGEST_TOKEN):
+architect dispatch my-feature lane-a \
+  --push-host  $HOST \
+  --push-token $INGEST_TOKEN
+```
+
+`--push-host` POSTs to `<HOST>/runs`, parses the new run id from the `201`
+response, derives `<HOST>/runs/<id>/ingest`, and streams there; the created run
+id and ingest URL are printed after dispatch starts. `--push-url` and
+`--push-host` are mutually exclusive, both require `--push-token`, and neither
+can be combined with `--detach` (the push tees the live pipe in-process).
+
+### Research lanes 🔭
+
+When an iteration needs facts the repo doesn't already have, fan out parallel
+**read-only** research lanes — detached `claude -p` researchers (no
+Edit/Write/Bash) that you supervise:
+
+```sh
+architect research dispatch 01-official-api.prompt.md 02-changelog.prompt.md
+architect research wait        # tails each lane's run.jsonl; --level 1-4, --quiet, --thinking
+architect research status      # status of dispatched runs
+```
+
+Researchers gather; the architect verifies the load-bearing claims against
+sources and writes the iteration's **Grounds** section.
+
+### Skills 🧠
+
+`architect install-skills` installs the bundled `architect`,
+`architect-research`, and `architect-vocabulary` skills for your harness:
+
+```sh
+architect install-skills                         # default: claude (~/.claude/skills/)
+architect install-skills --provider opencode     # or codex | pi
+architect install-skills --project               # into ./… instead of globally
+architect install-skills --dry-run               # show what would change
+```
+
+`architect-vocabulary` loads the system's terms and a short orientation when
+you're in a space but don't want to run the loop.
+
 ## Fish shell integration 🐟
 
-Shells can't let a child process change *their* working directory, so `architect`
-ships a small fish wrapper function. It also installs fish completions for commands,
-subcommands, spaces, statuses, config keys, and common config values. Install both
-into fish's autoloaded directories:
+Shells can't let a child process change *their* working directory, so `space`
+and `src` each ship a small fish wrapper function plus completions (commands,
+subcommands, spaces, statuses, config keys, repo refs). Install into fish's
+autoloaded directories:
 
 ```fish
-architect space shell fish install
+space shell fish install
+src shell fish install
 exec fish
 ```
 
-Restarting fish (or `exec fish`) lets the current terminal pick up the new autoloaded
-wrapper function. After that, `architect space new "Name of Space"` and
-`architect space use 20260531-name-of-space` will `cd` into the selected space once the
-CLI command succeeds. Every other command keeps normal CLI behavior. 🚪
-
-The function is written to `~/.config/fish/functions/space.fish` and completions to
-`~/.config/fish/completions/space.fish`, so there's no need to edit `config.fish`.
+After restarting fish (or `exec fish`), `space new "…"` and
+`space use <id>` will `cd` into the selected space once the command succeeds;
+every other command keeps normal CLI behavior. 🚪 The functions and completions
+are written under `~/.config/fish/`, so there's no need to edit `config.fish`.
 For one-off testing without installing:
 
 ```fish
-architect space shell init fish | source
+space shell init fish | source
 ```
 
 ## Configuration ⚙️
 
-Configuration follows the XDG base directory spec:
+Config lives at `~/.config/space-architect/config.yml` (XDG-aware) and defaults to:
 
 ```yaml
 version: 1
-spaces_dir: ~/src/spaces
-evergreen_dir: ~/src/evergreen
+base_dir: ~/architect            # spaces_dir + src_dir hang off this by default
 default_provider: github.com
 default_organization:
-git_clone_protocol: ssh
+git_clone_protocol: ssh          # ssh | https
 ```
 
-View current values: `architect space config show`. Set a value: `architect space config set KEY VALUE`.
+Derived defaults: `spaces_dir` → `<base_dir>/spaces`, `src_dir` (evergreen
+checkout root) → `<base_dir>/src`. Override either explicitly. View values with
+`space config show`; set one with `space config set KEY VALUE`. Editable keys:
+`base_dir`, `spaces_dir`, `src_dir`, `default_provider`, `default_organization`,
+`git_clone_protocol`.
 
-## Repos: evergreen, copy-on-write, concurrent 🌲
+## Repos: evergreen, copy-on-write, concurrent ⚡
 
 Repos are added to the current space under `repos/` and tracked in `space.yaml`.
-When an up-to-date local copy exists under `evergreen_dir` at
-`<evergreen_dir>/<provider>/<owner>/<name>` (e.g.
-`~/src/evergreen/github.com/example-org/example-app`), `architect` copies it into the
-space instead of cloning over the network — much faster, and a copy-on-write clone
-on APFS. ⚡ Set `evergreen_dir` to empty to always clone:
+When an up-to-date evergreen checkout exists at
+`<src_dir>/<host>/<owner>/<name>` (e.g.
+`~/architect/src/github.com/example-org/example-app`), `space` copies it into the
+space instead of cloning over the network — a copy-on-write clone on APFS. ⚡
+Set `src_dir` empty to always clone:
 
 ```sh
-architect space config set evergreen_dir ""
+space config set src_dir ""
 ```
 
-When no evergreen copy is found, the repo is cloned over the network. Clone URLs
-default to SSH (`git@github.com:example-org/example-app.git`). Prefer HTTPS?
+Clone URLs default to SSH (`git@github.com:example-org/example-app.git`); switch
+with `space config set git_clone_protocol https`. Multiple repos passed to
+`space repo add` are fetched **concurrently**, up to five at a time, on fibers —
+no threads, all cooperative. 🧵 After each repo lands, `space` runs `mise trust`
+in it. Each space also gets a workspace-local `tmp/` — use it instead of `/tmp`.
 
-```sh
-architect space config set git_clone_protocol https
-```
-
-When stdout/stderr are attached to a TTY, long-running repo operations show an
-interactive spinner. Multiple repos passed to `architect space repo add` are fetched
-**concurrently**, up to five at a time, on fibers — no threads, all cooperative. 🧵
-After each repo is in place, `architect` runs `mise trust` in it so local mise config
-is ready to go.
+## Embedding 📚
 
-Each space also gets a workspace-local `tmp/`. Use it instead of `/tmp` or
-`/var/tmp`; when using `mktemp`, point it at `tmp/`. 🗑️
+The library is split into three namespaces you can require independently:
 
-## The `src` engine: evergreen checkouts 🌿
+- **`Space::Core`** — the foundation: config, state, XDG, terminal, git/mise
+  clients, the space store. The `space` CLI runs on this alone.
+- **`Space::Architect`** — mission state, the builder harness, dispatch, and the
+  research supervisor.
+- **`Space::Src`** — the evergreen engine (tracking, sync, copy-on-write clone).
 
-`architect src …` exposes the **vendored** evergreen engine (from
-[repo-tender](https://github.com/jetpks/repo-tender)) directly — no separate
-installation needed. It keeps local clones under
-`~/src/evergreen/<host>/<owner>/<repo>` clean, on their default branch, and freshly
-fetched.
-
-```sh
-architect src repo add github.com/example-org/example-app   # tend it 🌲
-architect src sync                                           # run one sync pass
-architect src status                                         # per-repo evergreen status
-```
-
-When `architect space repo add` sees a matching evergreen copy, it copy-on-writes
-from it instead of hitting the network — instant provisioning. ⚡
-
-The vendored engine and space management share the same layout by design — both use
-`<evergreen_dir>/<host>/<owner>/<repo>` — so they line up with zero configuration:
-
-```sh
-architect src repo add github.com/example-org/example-app   # tend it: keep it evergreen 🌲
-architect space repo add example-app                         # copies it instantly ⚡
+```ruby
+require "space_core"       # just spaces
+require "space_architect"  # the full loop (pulls in core + src)
+require "space_src"        # just the evergreen engine
 ```
 
 ## Documentation 📖
 
 - **[Command Reference](docs/reference.md)** — every command, flag, and behavior
-- **[Design](docs/design.md)** — why spaces and the Architect Loop exist and how they're shaped
+- **[Design](docs/design.md)** — why spaces and the Architect Loop exist, and how they're shaped
+- **[Changelog](CHANGELOG.md)** — release history
 
 ## Development 🛠️
 

data/exe/architect

@@ -10,4 +10,4 @@ end
 
 require "space_architect"
 
-SpaceArchitect::CLI.run(ARGV, $stdout, $stderr)
+Space::Architect::CLI.run(ARGV, $stdout, $stderr)