docs(installer): record Phase 0.2 — the sidecar's CLI and settled data paths #84

wtclaude · 2026-08-04T15:49:12Z

wtclaude commented

2026-08-04 15:49:12 +00:00

Documentation half of installer Phase 0.2. Code PR: RunicGateway/link#24.

Phase 0.2 asked for two things — "confirm/settle default data paths" and "a way to read back config non-interactively so the installer does not have to scrape logs for the token." Both landed, and three sections of the plan asserted facts that change as a result, so they are corrected rather than appended to.

`installer/PLAN.md`

Status table — 0.1 merged (servuo-plugins#7 + #8; first overlay release v0.1.1 published), 0.2 in review, repo bootstrap merged (installer#1 + #2). 0.3 (bundle CI) is marked next and is now unblocked: both components it composes exist and have releases.
Phase 0 item 2 gains an "As built" subsection, matching the one item 1 already has. It records the choices that were made rather than inherited — the sidecar had no CLI at all before this:
- four hand-rolled flags, no parsing crate, and no flag that duplicates a config key;
- why --print-config provisions rather than only reporting, which collapses "set up the sidecar" and "find out its token" into the single call §6 needs;
- why config_created / token_generated exist — the values alone cannot tell a fresh install from a re-read, and a re-run must not report an existing token as newly minted;
- why no platform data directories are compiled in: that would give the same paths two owners and break cargo run in a working tree.
§2.3 (working-directory trap) — half-closed in the sidecar: a relative [store].path now anchors to the config file's directory, so pinning the config alone puts the database somewhere deterministic. The service definitions still pin both env vars, and the section now says why that is not redundant — deterministic is not the same as where this install wants it, and the config path itself is still CWD-relative by default.
§2.4 (token handoff) — the installer reads the handoff block out of one --print-config call. It explicitly never parses the log, which was the alternative and would have made the handoff depend on a log format that is not a contract.
§5 Phase 2 — the ordering this implies: run --print-config against the pinned config path before registering the service, so the service never starts against a config that does not exist yet.
§5 Phase 4 — which doctor rows the CLI answers (--version for the installed version and protocol, --print-config for the paths the installed binary actually resolves, rather than what install.json believes it was told).
§6 — every value in the printed block except the host comes from that one call, and only the host is substituted, because web.bind is frequently 0.0.0.0 and that is not something to hand a website. Plus: the printed token must not reach an installer log or a support bundle.

`link/INTEGRATION.md`

§1 said the token "is generated automatically on first run (the sidecar logs it)". That is no longer the supported way to get it. Replaced with the command, its full output, and the mapping onto what Admin → Shard asks for — including the secret-handling note.

AI-assisted contribution

This PR was written with AI assistance (Claude Code / Claude Opus 5); commits carry the Co-Authored-By trailer.

Documentation half of installer Phase 0.2. Code PR: RunicGateway/link#24. Phase 0.2 asked for two things — *"confirm/settle default data paths"* and *"a way to read back config non-interactively so the installer does not have to scrape logs for the token."* Both landed, and three sections of the plan asserted facts that change as a result, so they are **corrected rather than appended to**. ## `installer/PLAN.md` - **Status table** — 0.1 merged (servuo-plugins#7 + #8; first overlay release `v0.1.1` published), 0.2 in review, repo bootstrap merged (installer#1 + #2). 0.3 (bundle CI) is marked **next** and is now unblocked: both components it composes exist and have releases. - **Phase 0 item 2 gains an "As built" subsection**, matching the one item 1 already has. It records the choices that were made rather than inherited — the sidecar had no CLI at all before this: - four hand-rolled flags, no parsing crate, and no flag that duplicates a config key; - why `--print-config` *provisions* rather than only reporting, which collapses "set up the sidecar" and "find out its token" into the single call §6 needs; - why `config_created` / `token_generated` exist — the values alone cannot tell a fresh install from a re-read, and a re-run must not report an existing token as newly minted; - why no platform data directories are compiled in: that would give the same paths two owners and break `cargo run` in a working tree. - **§2.3 (working-directory trap)** — half-closed *in the sidecar*: a relative `[store].path` now anchors to the config file's directory, so pinning the config alone puts the database somewhere deterministic. The service definitions still pin both env vars, and the section now says why that is not redundant — deterministic is not the same as where this install wants it, and the config path itself is still CWD-relative by default. - **§2.4 (token handoff)** — the installer reads the handoff block out of one `--print-config` call. It explicitly **never parses the log**, which was the alternative and would have made the handoff depend on a log format that is not a contract. - **§5 Phase 2** — the ordering this implies: run `--print-config` against the pinned config path *before* registering the service, so the service never starts against a config that does not exist yet. - **§5 Phase 4** — which `doctor` rows the CLI answers (`--version` for the installed version and protocol, `--print-config` for the paths the installed binary actually resolves, rather than what `install.json` believes it was told). - **§6** — every value in the printed block except the host comes from that one call, and **only** the host is substituted, because `web.bind` is frequently `0.0.0.0` and that is not something to hand a website. Plus: the printed token must not reach an installer log or a support bundle. ## `link/INTEGRATION.md` §1 said the token "is generated automatically on first run (the sidecar logs it)". That is no longer the supported way to get it. Replaced with the command, its full output, and the mapping onto what Admin → Shard asks for — including the secret-handling note. ## AI-assisted contribution - [x] This PR was written with AI assistance (Claude Code / Claude Opus 5); commits carry the `Co-Authored-By` trailer.

wtclaude added 1 commit 2026-08-04 15:49:22 +00:00

docs(installer): record Phase 0.2 — the sidecar's CLI and settled data paths c1957f0bfb

Phase 0.2 landed in link#24: the sidecar gained a four-flag CLI, --print-config,
and config-anchored data paths. Three sections of the installer plan asserted
facts that change as a result, so they are corrected rather than appended to.

- Status table: 0.1 merged (servuo-plugins#7/#8, overlay v0.1.1 released), 0.2 in
  review, repo bootstrap merged. 0.3 (bundle CI) is next and now unblocked — both
  components it composes exist.
- Phase 0 item 2 gains an "As built" subsection matching item 1's: why four
  hand-rolled flags rather than a parsing crate, why --print-config provisions
  instead of only reporting, why config_created/token_generated exist, and why no
  platform data directories are compiled into the binary.
- §2.3 (working-directory trap): half-closed in the sidecar — a relative
  [store].path now anchors to the config file's directory — while the service
  definitions still pin both env vars, and why that is not redundant.
- §2.4 (token handoff): the installer reads the handoff block out of one
  --print-config call and never parses the log, which is not a contract.
- §5 Phase 2 / Phase 4, §6: the ordering that follows (print-config before service
  registration), which doctor rows the CLI answers, that only the host is
  substituted into the printed URLs because web.bind is often 0.0.0.0, and that the
  printed token must not reach a log or support bundle.
- link/INTEGRATION.md §1: how to read the token back, replacing "the sidecar logs
  it" with the supported command and its output.

Co-Authored-By: Claude <noreply@anthropic.com>

wtclaude referenced this pull request from RunicGateway/link

2026-08-04 15:49:52 +00:00

feat(sidecar): make the sidecar installable — CLI, `--print-config`, anchored data paths #24

whitlocktech approved these changes 2026-08-04 15:55:47 +00:00

whitlocktech merged commit d1cb3e9511 into main

2026-08-04 15:55:59 +00:00

whitlocktech deleted branch docs/installer-phase-0.2

2026-08-04 15:56:00 +00:00

whitlocktech referenced this issue from a commit

2026-08-04 15:56:01 +00:00

Merge pull request 'docs(installer): record Phase 0.2 — the sidecar's CLI and settled data paths' (#84) from docs/installer-phase-0.2 into main

Sign in to join this conversation.