From fb5aff40f4b0cb41e89d5dc664f757baf34704d5 Mon Sep 17 00:00:00 2001 From: Barak Korren Date: Sun, 5 Jul 2026 13:51:15 +0300 Subject: [PATCH 1/2] docs(adr): add ADR 0066 for interactive admin install guide Record the decision to revive admin install as a guided orchestrator over existing mint/github/inference/repos phases, with a shared decision tree for humans and agent skills. Signed-off-by: Barak Korren Co-authored-by: Cursor --- .../0066-interactive-admin-install-guide.md | 108 ++++++++++++++++++ docs/architecture.md | 1 + 2 files changed, 109 insertions(+) create mode 100644 docs/ADRs/0066-interactive-admin-install-guide.md diff --git a/docs/ADRs/0066-interactive-admin-install-guide.md b/docs/ADRs/0066-interactive-admin-install-guide.md new file mode 100644 index 000000000..3f57edf96 --- /dev/null +++ b/docs/ADRs/0066-interactive-admin-install-guide.md @@ -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. + +## 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. + +## Decision + +1. **Revive `admin install` as a guide, not a monolith.** The command + orchestrates installation; it does not re-inline GCP provisioning, mint + 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. + +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. +- 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. +- Implementation scope (wizard UI, tree loader, skill packaging) is follow-on + work; this ADR records the architectural choice only. diff --git a/docs/architecture.md b/docs/architecture.md index 26c3d2874..2c92d2d5a 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -47,6 +47,7 @@ Infrastructure platform choice and configuration are specified in the adopting o - Event-driven stage dispatch: eliminate `workflow_dispatch` + `gh workflow run` fan-out from `dispatch.yml` in favor of synchronous `workflow_call` so the dispatched run stays linked to the caller ([ADR 0041](ADRs/0041-synchronous-workflow-call-event-dispatch.md)). - Multi-repo management: a `fullsend repos` subcommand group with a declarative `repos.yaml` manifest for managing per-repo installations at scale — bulk install, status, sync, upgrade, and removal across repos and orgs ([ADR 0057](ADRs/0057-repos-management.md)). - Dispatch version-skew resolution: per-repo `reusable-dispatch.yml` inlines stage workflow jobs directly, eliminating `@v0` references to `reusable-{stage}.yml` ([ADR 0062](ADRs/0062-dispatch-version-skew.md)). +- Interactive install entry point: `admin install` is the guided orchestrator over existing `mint` / `github` / `inference` / `repos` phases, driven by a shared decision tree for humans and agent skills — not a monolithic provisioner ([ADR 0066](ADRs/0066-interactive-admin-install-guide.md)). **Open questions:** From 8da72c5824b689d26b3644e2e5ca562365e1eaab Mon Sep 17 00:00:00 2001 From: Barak Korren Date: Sun, 5 Jul 2026 14:02:31 +0300 Subject: [PATCH 2/2] docs(adr): reconcile admin install deprecation with ADR 0066 Clarify that the monolithic all-in-one admin install path is deprecated, not the future guided orchestrator described in ADR 0066. Update advanced-setup and cli-internals to cross-reference the ADR and note the interactive wizard is follow-on work. Signed-off-by: Barak Korren Co-authored-by: Cursor --- docs/guides/dev/cli-internals.md | 7 ++++++- docs/guides/infrastructure/advanced-setup.md | 17 ++++++++++++++--- 2 files changed, 20 insertions(+), 4 deletions(-) diff --git a/docs/guides/dev/cli-internals.md b/docs/guides/dev/cli-internals.md index 686ffc586..8e65d641e 100644 --- a/docs/guides/dev/cli-internals.md +++ b/docs/guides/dev/cli-internals.md @@ -98,7 +98,12 @@ The `mint`, `inference`, and `github` subcommands decompose setup into role-spec The typical handoff: a GCP admin runs `mint deploy`, `mint enroll`, and `inference provision`, then passes the mint URL and WIF provider resource name to a GitHub maintainer who runs `github setup --mint-url=... --inference-wif-provider=...`. See [Advanced setup](../infrastructure/advanced-setup.md). -> **Note:** The legacy `admin install` command wraps all phases into a single invocation but is deprecated. The standalone commands above are the recommended path. See the [Unified Installation Flow](#unified-installation-flow) section below for how the phases are structured internally. +> **Note:** The legacy monolithic `admin install` (one opaque invocation for all +> phases) is deprecated; use the standalone commands above for now. [ADR 0066](../../ADRs/0066-interactive-admin-install-guide.md) +> accepts `admin install` as a future interactive guided orchestrator over those +> same phases (not a monolith); that wizard is follow-on work. See the +> [Unified Installation Flow](#unified-installation-flow) section below for how the +> phases are structured internally. ### Token Resolution Chain diff --git a/docs/guides/infrastructure/advanced-setup.md b/docs/guides/infrastructure/advanced-setup.md index bdbaf5287..720b30a9b 100644 --- a/docs/guides/infrastructure/advanced-setup.md +++ b/docs/guides/infrastructure/advanced-setup.md @@ -185,9 +185,20 @@ fullsend github setup "$ORG_NAME" \ > **Note:** IAM policy bindings may take several minutes to propagate. If agent workflows fail with a permission error immediately after setup, wait a few minutes and retry. -## Deprecated: all-in-one admin install - -> **Deprecated.** The `fullsend admin install` all-in-one command that provisions GCP mint, inference, and GitHub in a single invocation is deprecated. Use the [standalone commands](../getting-started/operations.md#standalone-commands) instead: `fullsend inference provision` + `fullsend github setup` for per-repo, or `fullsend mint deploy` + `fullsend mint enroll` + `fullsend github setup` for per-org. See [Getting Started](../getting-started/configuring-github.md) for the recommended per-repo flow. +## Deprecated: monolithic `admin install` (not the guided entry point) + +> **Deprecated (monolithic mode).** Running `fullsend admin install` as a single +> opaque invocation that provisions GCP mint, inference, and GitHub together is +> deprecated. Use the [standalone commands](../getting-started/operations.md#standalone-commands) +> today: `fullsend inference provision` + `fullsend github setup` for per-repo, or +> `fullsend mint deploy` + `fullsend mint enroll` + `fullsend github setup` for +> per-org. See [Getting Started](../getting-started/configuring-github.md) for the +> recommended per-repo flow. +> +> **Accepted direction ([ADR 0066](../../ADRs/0066-interactive-admin-install-guide.md)):** +> `admin install` will become an interactive guided orchestrator over those same +> standalone phases (decision tree + `--plan`), not a monolithic provisioner. +> That wizard is follow-on implementation work — it is not available in the CLI yet. ## See Also