chore: publish prep — scrub, license, README, CI

- Module path: github.com/cailmdaley/shuttle-cli → github.com/cailmdaley/shuttle
- Schema $id: same rewrite
- Remove personal paths (/Users/cd280747, ~/Documents/projects/lightcone,
  ~/wedding) from comments and test fixtures
- Replace with generic examples or architecture-neutral descriptions
- Add LICENSE (Apache 2.0) and NOTICE (Symphony attribution)
- Rewrite README: principles-first, three-artifacts, install path, lineage
- Rewrite CLAUDE.md: contributor-facing, no loom paths or personal context
- Add .github/workflows/ci.yml: mix compile --warnings-as-errors, mix test,
  go test ./pkg/schema/...
- Add CONTRIBUTING.md
- Gitignore bin/shuttle (escript) and .felt (user-local symlink)

All tests pass: 110 Elixir + Go schema suite.

Author: cailmdaley

.github/workflows/ci.yml

@@ -0,0 +1,60 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  elixir:
+    name: Elixir (mix compile + mix test)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Elixir
+        uses: erlef/setup-beam@v1
+        with:
+          otp-version: "27"
+          elixir-version: "1.17"
+
+      - name: Cache deps
+        uses: actions/cache@v4
+        with:
+          path: deps
+          key: ${{ runner.os }}-mix-${{ hashFiles('**/mix.lock') }}
+          restore-keys: ${{ runner.os }}-mix-
+
+      - name: Cache _build
+        uses: actions/cache@v4
+        with:
+          path: _build
+          key: ${{ runner.os }}-build-${{ hashFiles('**/mix.lock') }}
+          restore-keys: ${{ runner.os }}-build-
+
+      - name: Install dependencies
+        run: mix deps.get
+
+      - name: Compile (warnings as errors)
+        run: mix compile --warnings-as-errors
+
+      - name: Run tests
+        run: mix test
+
+  go:
+    name: Go (build + test)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "1.22"
+
+      - name: Build CLI
+        run: go build ./cmd/shuttle
+
+      - name: Run tests
+        run: go test ./pkg/schema/...

.gitignore

@@ -22,6 +22,12 @@ erl_crash.dump
 # Ignore package tarball (built via "mix hex.build").
 shuttle-*.tar
 
+# Shuttle daemon escript (built via `mix escript.build`)
+/bin/shuttle
+
 # Go binaries (build with `go build` from cmd/shuttle/)
 /bin/shuttle-ctl
 /shuttle
+
+# felt symlink (user-local; points to the user's felt store)
+.felt

CLAUDE.md

@@ -1,14 +1,11 @@
-# Shuttle — Agent Notes
+# Shuttle — Contributor Notes
 
 Local OTP-supervised dispatcher for felt constitution workers. Polls the felt
 tree, launches one tmux worker per eligible fiber, exposes a snapshot surface
-for Portolan and other consumers.
+for dashboards and other consumers.
 
-**Status: Stages 0–6 complete; Stage 7 (BEAM distribution / SSH-drop resilience) deferred.**
-The Elixir engine is the production dispatcher; portolan's TS engine is retired.
-See [[ai-futures/shuttle/constitution-shuttle-standalone]] for the canonical invariants.
-
-The repo has no git remote — local-only, like portolan. Don't add one without intent.
+**Status: Stages 0–6 complete; Stage 7 (BEAM distribution / SSH-drop resilience) in progress.**
+The Elixir daemon is the production dispatcher.
 
 ## Build + lifecycle
 
@@ -17,7 +14,7 @@ running daemon until you restart. Use the Makefile:
 
 ```
 make build      # mix escript.build → bin/shuttle (MIX_ENV=dev)
-make start      # nohup detached; logs → ~/Library/Logs/shuttle.log
+make start      # nohup detached; logs → ~/Library/Logs/shuttle.log (macOS)
 make stop       # SIGTERM with 5s grace
 make restart    # build + stop + start (the load-bearing daemon target)
 make cli        # go build → ~/go/bin/shuttle-ctl (load-bearing CLI target)
@@ -30,17 +27,11 @@ make clean      # rm _build and stray Elixir.*.beam at project root
 **Two artifacts, two languages, two release cadences.** The Elixir daemon
 (`bin/shuttle`) and the Go CLI (`~/go/bin/shuttle-ctl`) are independent —
 rebuilding one never implies rebuilding the other. Editing `cmd/shuttle/*.go`
-needs `make cli`; editing `lib/shuttle/*.ex` needs `make restart`. When the
-kanban or any portolan path starts shelling out to a new shuttle-ctl verb,
-`make cli` becomes load-bearing — a stale binary breaks transitions
-silently. See
-[[ai-futures/portolan/gotchas/gotcha-shuttle-ctl-binary-stale-after-source-update]].
-
-**`bin/shuttle` is an escript** — it bundles BEAM bytecode at build time and loads it at boot. A restart without `make build` is a no-op for picking up source edits; `mix compile` without restart is a no-op for an already-running daemon. **`make restart` always.** When `shuttle-ctl status` sees a fiber but `bin/shuttle snapshot` doesn't list it as eligible, the daemon is stale.
+needs `make cli`; editing `lib/shuttle/*.ex` needs `make restart`.
 
-Default `MIX_ENV=dev` matches the localhost:4000 endpoint config in
-`config/dev.exs`. The Phoenix endpoint binds 127.0.0.1:4000 only when
-`server: true` is set there — don't propagate that to other envs.
+**`bin/shuttle` is an escript** — it bundles BEAM bytecode at build time and
+loads it at boot. A restart without `make build` is a no-op for picking up
+source edits. `make restart` always.
 
 If `mix escript.build` warns about "redefining module Shuttle.X" with the
 "current version loaded from Elixir.Shuttle.X.beam" hint, run `make clean`
@@ -55,8 +46,8 @@ bin/shuttle dispatch <fiber-id>               # one-shot dispatch
 
 # shuttle-ctl — agent-facing CLI; offline; schema-validating
 shuttle-ctl status                            # all fibers with shuttle: blocks
-shuttle-ctl status --all                      # local + every configured remote (via daemon /state/composite)
-shuttle-ctl status --remote candide           # single remote, filtered from the composite snapshot
+shuttle-ctl status --all                      # local + every configured remote
+shuttle-ctl status --remote <name>            # single remote
 shuttle-ctl ps                                # live tmux workers only
 shuttle-ctl install <fiber> [-m <agent-id>] [--disabled]
 shuttle-ctl repeat <fiber> --schedule "0 9 * * 1-5" --tz Europe/Paris
@@ -68,85 +59,92 @@ shuttle-ctl migrate --dry-run                 # preview eligibility migration
 
 ## Critical invariants
 
-- **tmux owns the worker process; Shuttle owns the watcher.** Workers stay attachable via `tmux attach -t shuttle-<fiber-id>`. Supervise watchers, not workers.
-- **Felt is the data layer; Shuttle shells out to the felt CLI.** Don't import felt internals.
-- **Agent records live in one source of truth: `share/agents.json`.** Both runtimes (Elixir daemon, Go CLI) embed it at compile time — Elixir via `@external_resource` + `File.read!` in `lib/shuttle/agents.ex`, Go via `//go:embed` (generated `pkg/schema/agents_embedded.go`). Edit the JSON, then `make restart`. There is no `config/agents.exs` and no hand-edited fallback list anywhere — see `[[ai-futures/shuttle/finding-agent-registry-four-mirrors]]` for the cleanup that landed.
-- **`shuttle.agent` field drives agent selection.** The `shuttle:` block's `agent:` field resolves against the registry. Bare `codex`/`pi` felt tags resolve via back-compat aliases when no `shuttle.agent` is set; default agent is `claude-sonnet`.
-- **shuttle-ctl is the agent-facing CLI.** Write verbs validate before write; works offline. Elixir `bin/shuttle` handles daemon lifecycle and dispatch only.
-- **No tag predicate for dispatch.** `constitution` is a human convention only — a fiber with a `shuttle:` block dispatches with or without it. Tags are free-form qualitative noticings; only `idea` is read by Portolan's kanban (for column placement).
+- **tmux owns the worker process; Shuttle owns the watcher.** Workers stay
+  attachable via `tmux attach -t shuttle-<fiber-id>`. Supervise watchers,
+  not workers.
+- **Felt is the data layer; Shuttle shells out to the felt CLI.** Don't
+  import felt internals.
+- **Agent records live in one source of truth: `share/agents.json`.** Both
+  runtimes (Elixir daemon, Go CLI) embed it at compile time — Elixir via
+  `@external_resource` + `File.read!` in `lib/shuttle/agents.ex`, Go via
+  `//go:embed` (generated `pkg/schema/agents_embedded.go`). Edit the JSON,
+  then `make restart`. There is no `config/agents.exs`.
+- **`shuttle.agent` field drives agent selection.** The `shuttle:` block's
+  `agent:` field resolves against the registry. Default agent is
+  `claude-sonnet`.
+- **shuttle-ctl is the agent-facing CLI.** Write verbs validate before
+  write; works offline. `bin/shuttle` handles daemon lifecycle and dispatch.
+- **No tag predicate for dispatch.** The `shuttle:` block's `enabled: true`
+  field is the dispatch signal. Tags are free-form qualitative noticings;
+  only `idea` is load-bearing for Portolan's kanban column placement.
 
 ## How dispatch works
 
-- **Poller** (`lib/shuttle/poller.ex`) is the single GenServer that owns the
-  tick. It walks each configured `felt_host`, parses each `*.md` file's
-  frontmatter, and considers a fiber eligible iff `shuttle.enabled: true` AND
-  `status in ["open", "active"]` AND not already running/claimed AND deps
-  satisfied.
-- **Configured hosts** come from `LOOM_HOMES` (comma-separated) →
-  persisted `~/.shuttle/felt_hosts.json` → `LOOM_HOME` → default `~/loom`.
-  `POST /api/v1/felt-hosts` rewrites the persisted file; earlier-configured
-  hosts win on fiber-id collisions across hosts.
+- **Poller** (`lib/shuttle/poller.ex`) owns the tick. It walks each
+  configured felt host, pulls candidate metadata via `felt ls --json` and
+  per-fiber detail via `felt show -j`, and considers a fiber eligible iff
+  `shuttle.enabled: true` AND `status in ["open", "active"]` AND not
+  already running AND deps satisfied.
+- **Configured hosts** come from `LOOM_HOMES` (comma-separated env var) →
+  persisted `~/.shuttle/felt_hosts.json` → `LOOM_HOME` → `~/loom`.
+  `POST /api/v1/felt-hosts` rewrites the persisted file.
 - **Dispatcher** (`lib/shuttle/dispatcher.ex`) resolves the agent via
   `Shuttle.Agents.resolve_by_name/1` against the embedded registry, spawns
   `shuttle-<fiber-id>` tmux session.
-- **Standing roles** are recurring fibers — `shuttle.kind: standing` with a
-  cron `schedule:`. Daemon dispatches only when `next_due_at` is due AND
-  `review.state` is `scheduled` or `accepted`. Worker exit flips state to
-  `awaiting`; `shuttle-ctl accept` advances `next_due_at`.
+- **Standing roles** — `shuttle.kind: standing` with a cron `schedule:`.
+  Dispatches only when `next_due_at` is due AND `review.state` is
+  `scheduled` or `accepted`. Worker exit flips state to `awaiting`;
+  `shuttle-ctl accept` advances `next_due_at`.
+
+## Dispatch prompt structure
+
+All prompt variants share this shape (`compose_prompt/3` in dispatcher.ex):
+
+1. **Orientation paragraph** — what Shuttle is, what the worker is here to
+   do, how the practice loads. Per-prompt, not boilerplate. Goes first
+   because in causal attention every downstream token sees the prefix.
+2. **`Fiber: <id>`** (and `Run: <run-id>` for standing) — identity lines.
+3. **`From User · <relative time>`** — the most recent `--kind
+   review-comment` event, if any. Pulled fresh at dispatch.
+
+The fiber's outcome and last editorial event are not inlined — they're
+already in scope after `felt show <id>` and `felt history <id>`, which
+the shuttle skill prescribes the worker calls on arrival.
 
 ## Inspecting state
 
-```
-make status                              # daemon-side view (ps + snapshot)
+```bash
 shuttle-ctl status                       # Go walker view (independent of daemon)
-shuttle-ctl status -j                    # JSON
 bin/shuttle snapshot                     # raw JSON snapshot
-~/Library/Logs/shuttle.log               # daemon stdout/stderr
+make status                              # daemon-side view (ps + snapshot)
+~/Library/Logs/shuttle.log               # daemon stdout/stderr (macOS)
 tmux ls | grep '^shuttle-'               # live workers
-curl -s http://127.0.0.1:4000/api/v1/agents | jq   # agent registry as JSON
-curl -s http://127.0.0.1:4000/api/v1/state | jq    # full orchestrator state
-curl -s http://127.0.0.1:4000/api/v1/state/composite | jq   # local + per-remote snapshots
+curl -s http://127.0.0.1:4000/api/v1/agents | jq
+curl -s http://127.0.0.1:4000/api/v1/state | jq
+curl -s http://127.0.0.1:4000/api/v1/state/composite | jq
 ```
 
-**Cross-host visibility.** `--all` and `--remote` go through the local
-daemon's `/api/v1/state/composite`; the daemon's `RemoteRegistry` polls
-each configured remote (`config :shuttle, :remotes, [...]`) over its
-SSH-tunnel-mapped port and merges the snapshots with freshness flags.
-The CLI never talks to remote daemons directly — `SHUTTLE_DAEMON_URL`
-overrides which local daemon to query, but remote URLs live in mix
-config alone. See [[ai-futures/shuttle/constitution-shuttle-remote-dispatch]].
+Dispatch sanity ladder:
 
-## Dispatch prompt structure
-
-The fresh, resume, and standing-run prompts all share the same shape (`compose_prompt/3` in `lib/shuttle/dispatcher.ex`):
-
-1. **Orientation paragraph** — what Shuttle is, what the worker is here to do, how the practice loads. Per-prompt, not boilerplate. Goes first because in causal attention every downstream token sees the prefix.
-2. **`Fiber: <id>`** (and `Run: <run-id>` for standing) — identity lines, grep-able.
-3. **`From User · <relative time>`** — the most recent `--kind review-comment` event, if any. Pulled fresh at dispatch. The user's intent, inlined so it sits in attention prefix.
-
-The fiber's outcome and last editorial event are *not* inlined — they're already in scope after `felt show <id>` (outcome + Recent line) and `felt history <id>` (full chain), which the shuttle skill prescribes the worker calls on arrival. Inlining either duplicates state and risks drift between the prompt's snapshot and felt's view.
-
-Operational instructions (read the constitution, exit before half-full, append an editorial event, `kill $PPID`, standing-run awaiting-review handoff) live in the `shuttle` and `felt` skills, not the prompt. The prompt's job is orientation; duplicating practice means drift.
-
-A useful sanity ladder when something isn't dispatching:
-
-1. `shuttle-ctl status` shows `enabled: true, idle, oneshot`? → fiber is well-formed and the Go walker sees it.
-2. `bin/shuttle snapshot` lists it under `eligible[]` with `state: running`? → daemon dispatched it.
-3. If shuttle-ctl sees it but daemon doesn't → daemon binary is stale. `make restart`.
-4. If daemon sees it but agent never appears → check `share/agents.json` for the resolved agent's `cli` and that the wrapper is on `PATH`.
-5. If the snapshot has no `felt_hosts:` field → binary pre-`297a24d`. Same fix: `make restart`.
+1. `shuttle-ctl status` shows `enabled: true, idle, oneshot`? → fiber is
+   well-formed and the Go walker sees it.
+2. `bin/shuttle snapshot` lists it under `eligible[]`? → daemon dispatched.
+3. shuttle-ctl sees it but daemon doesn't → daemon binary is stale.
+   `make restart`.
+4. Daemon sees it but agent never appears → check `share/agents.json` for
+   the resolved agent's `cli` and that the wrapper is on `PATH`.
 
 ## Codebase layout
 
 ```
-shuttle/                     project root (this dir, flat — no nested shuttle/)
+shuttle/
 ├── CLAUDE.md                you're reading it
 ├── Makefile                 build + daemon lifecycle
 ├── mix.exs                  Mix project
 ├── bin/shuttle              the daemon escript (built artifact)
 ├── lib/                     Elixir source
 │   ├── shuttle/poller.ex    discover + eligibility + retry queue
-│   ├── shuttle/dispatcher.ex  agent resolution, tmux launch, session-UUID capture
+│   ├── shuttle/dispatcher.ex  agent resolution, tmux launch
 │   ├── shuttle/agents.ex    agent registry — reads share/agents.json at compile time
 │   └── shuttle_web/         agent-API HTTP endpoints (/api/v1/...)
 ├── cmd/shuttle/             Go CLI (shuttle-ctl)
@@ -163,21 +161,12 @@ shuttle/                     project root (this dir, flat — no nested shuttle/
 
 ## Tests
 
-```
-mix test                   # full Elixir suite (78 tests, ~7s)
+```bash
+mix test                   # full Elixir suite (110 tests, ~7s)
 mix test --only focus      # tagged subset
 go test ./pkg/schema/...   # Go schema tests
 ```
 
-Disk-walking tests use real fixture directories under `test/support/` rather
-than mocks — the walker is a thin filesystem read so this is faster and
-catches more.
-
-## Pointers
+## Contributing
 
-- Constitution: `felt show ai-futures/shuttle/constitution-shuttle-standalone`
-- SPEC: `~/loom/.felt/ai-futures/shuttle/SPEC.md`
-- Agent registry: `share/agents.json` (single source of truth — see invariants above)
-- Loom shell wrappers: `~/loom/shell-functions.sh` (claude, codex, pi, kimi, glm)
-- Shuttle skill: `~/.claude/skills/shuttle/SKILL.md`
-- Fibers: `ai-futures/shuttle/` in `~/loom/.felt/` — design fibers, constitutions (cutover, multi-host, CLI, etc.), gotchas, postmortems.
+See `CONTRIBUTING.md`.

CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Contributing to Shuttle
+
+Thank you for your interest in Shuttle.
+
+## Getting started
+
+```bash
+git clone https://github.com/cailmdaley/shuttle
+cd shuttle
+mix deps.get && mix compile
+make cli
+```
+
+Requirements: Erlang/OTP 26+, Elixir 1.16+, Go 1.21+, the `felt` CLI.
+
+## Running tests
+
+```bash
+mix test                   # Elixir suite
+go test ./pkg/schema/...   # Go schema tests
+```
+
+CI runs `mix compile --warnings-as-errors`, `mix test`, and
+`go test ./pkg/schema/...` on every PR.
+
+## Invariants
+
+Before opening a PR, verify:
+
+- `mix compile --warnings-as-errors` passes
+- `mix test` passes
+- `go test ./pkg/schema/...` passes
+- No personal paths (`~/loom`, `/Users/...`) in tracked files
+- `share/agents.json` is the only agent registry — do not add a parallel
+  registry in Elixir config or Go source
+
+## Scope
+
+Shuttle is deliberately personal-scale: no auth model, no team conventions,
+felt as the only work source. Contributions that add general-purpose
+infrastructure are welcome; contributions that add a specific integration
+layer belong in a fork or a `Shuttle.WorkSource` adapter once that
+abstraction lands.
+
+## Opening issues
+
+- **Bugs:** include steps to reproduce and the output of `bin/shuttle snapshot`.
+- **Features:** describe the problem, not just the solution. A concrete
+  use-case helps.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under
+the Apache License 2.0.