docs(adr): add ADR 0066 for interactive admin install guide #3020
+129
−4
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,108 @@ | ||
| --- | ||
| title: "66. Interactive admin install as guided installation orchestrator" | ||
| status: Accepted | ||
| relates_to: | ||
| - agent-infrastructure | ||
| - human-factors | ||
| - contributor-guidance | ||
| topics: | ||
| - install | ||
| - cli | ||
| - skills | ||
| - interactive | ||
| --- | ||
|
|
||
| # 66. Interactive admin install as guided installation orchestrator | ||
|
|
||
| Date: 2026-07-05 | ||
|
|
||
| ## Status | ||
|
|
||
| Accepted | ||
|
|
||
| ## Context | ||
|
|
||
| Fullsend installation spans mint trust, inference WIF, GitHub Apps, scaffold | ||
| delivery, and per-repo vs per-org scope. Standalone commands (`mint`, | ||
| `github`, `inference`, `repos`) already exist ([ADR 0029](0029-central-token-mint-secretless-fullsend.md), | ||
| [ADR 0033](0033-per-repo-installation-mode.md), [ADR 0057](0057-repos-management.md)), | ||
| and user-facing docs recently deprecated the all-in-one `admin install` as a | ||
| monolithic path in favor of those phases. | ||
|
|
||
| That split reduced coupling but increased cognitive load: adopters must | ||
| understand which role runs which phase, whether to use the hosted mint or a | ||
| private one, how many GCP projects are involved, and whether | ||
| [ADR 0047](0047-vendored-installs-with-vendor-flag.md) vendoring applies — from | ||
| a single repo on hosted services through a multi-org footprint with private | ||
| mints and several inference accounts. Agents assisting onboarding face the same | ||
| matrix without a single machine-readable decision model. | ||
|
Comment on lines
+32
to
+38
Member
There was a problem hiding this comment. I dont think this is true. The decoupling removed cognitive load. Users know They can defer acquiring the knowledge, they are not even expose to much of this knowledge up front. That is reserved for "next steps". So I would say this premise is false |
||
|
|
||
| ## Options | ||
|
|
||
| ### Option A: Standalone commands only (status quo docs) | ||
|
|
||
| Users and agents read guides and invoke `mint` / `github` / `inference` | ||
| directly. Low CLI complexity; high expertise burden. | ||
|
|
||
| ### Option B: Interactive `admin install` orchestrator (chosen) | ||
|
|
||
| `admin install` becomes a guided entry point that walks the decision tree, | ||
| then delegates execution to existing subcommands. Same tree drives agent | ||
| skills. | ||
|
|
||
| ### Option C: New top-level `fullsend install` | ||
|
|
||
| Same behavior as B but a new command. Rejected — `admin install` is already the | ||
| familiar entry point and matches org-admin mental models. | ||
|
Comment on lines
+53
to
+56
Member
There was a problem hiding this comment. I would go with this, if we aim to simplify, we should surface this to top level so it is easier. |
||
|
|
||
| ## Decision | ||
|
|
||
| 1. **Revive `admin install` as a guide, not a monolith.** The command | ||
| orchestrates installation; it does not re-inline GCP provisioning, mint | ||
|
Member
There was a problem hiding this comment. "it does not re-inline GCP provisioning, ming dpeloy or GitHub layer logic" seems contradictory with the next point, where it says that non-interactive usage keeps today's explicit flags. I would just keep it as an interactive way of installing. |
||
| deploy, or GitHub layer logic. Each step invokes the existing standalone | ||
| commands (or their library equivalents) with composed flags. | ||
|
|
||
| 2. **Interactive by default on a TTY.** When stdin is a terminal and required | ||
| flags are absent, `admin install` runs a guided flow. Non-interactive use | ||
| keeps today's explicit flags (`--mint-url`, `--inference-project`, etc.). | ||
| Add `--guided` (force interactive) and `--plan` (print the composed command | ||
| sequence without executing). | ||
|
|
||
| 3. **Published decision tree.** Maintain a versioned install decision tree | ||
| (YAML) in-repo describing questions, branches, prerequisites, and the | ||
| subcommand(s) each leaf executes. The CLI loads it; changes to install | ||
| matrix update the tree, not scattered help text. | ||
|
Comment on lines
+71
to
+74
Member
There was a problem hiding this comment. Could you add an example of the decision tree? I don't see the difference between storing a decision tree and just storing the answers. |
||
|
|
||
| 4. **Coverage.** The tree must reach at least: | ||
| - single-repo + hosted mint + shared inference (zero-GCP GitHub path); | ||
| - self-hosted or private mint ([ADR 0059](0059-public-mint-mode-with-wildcard-allowlists.md) | ||
| tight vs public); | ||
| - multiple GCP projects / inference accounts; | ||
| - bulk per-repo rollout via `repos` ([ADR 0057](0057-repos-management.md)); | ||
| - optional `--vendor` ([ADR 0047](0047-vendored-installs-with-vendor-flag.md)). | ||
| Per-org mode remains a deprecated branch per [ADR 0044](0044-deprecate-per-org-installation-mode.md), | ||
| shown only when explicitly chosen, with migration guidance. | ||
|
|
||
| 5. **Agent skills on the same tree.** Provide an install-guidance skill that | ||
| loads the decision tree and accepts optional context (org size, existing | ||
| mint URL, compliance constraints, repos in scope). Agents traverse the tree, | ||
| explain trade-offs, and emit the same `--plan` output humans would get — | ||
| without bypassing authorization or inventing flags outside the tree. | ||
|
|
||
| 6. **Normative spec deferred.** The tree schema and leaf command templates are | ||
| documented alongside the artifact; a `docs/normative/` contract is out of | ||
| scope until a second consumer (e.g. web installer) needs byte-level | ||
| interoperability ([ADR 0015](0015-normative-specifications-directory.md)). | ||
|
|
||
| ## Consequences | ||
|
|
||
| - User-facing docs that deprecated all-in-one `admin install` should be | ||
| annotated: deprecated as an opaque monolith, not as the guided entry point. | ||
|
Comment on lines
+99
to
+100
Member
There was a problem hiding this comment. I don't see value in annotating them, just remove them and add the new ones in place. The docs would talk about the command being an interactive experience. |
||
| - The CLI must keep standalone commands as the execution layer so automation | ||
| and skills do not depend on TTY prompts. | ||
| - The decision tree becomes a maintained product artifact; install changes | ||
| require tree updates and tests. | ||
| - Agents gain a bounded, testable install guide instead of improvising from | ||
| prose docs. | ||
|
Comment on lines
+103
to
+106
Member
There was a problem hiding this comment. Could you expand a bit on the testability? |
||
| - Implementation scope (wizard UI, tree loader, skill packaging) is follow-on | ||
| work; this ADR records the architectural choice only. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Per-org is deprecated, not worth adding it here in my opinion.