docs(adr): add ADR 0066 for interactive admin install guide

[ifireball]

Summary

• Add ADR 0066: revive admin install as an interactive guided orchestrator, not a monolithic provisioner.
• The command walks a versioned install decision tree (YAML) and delegates to existing mint / github / inference / repos phases.
• Same tree drives a future agent install-guidance skill; --plan emits composed commands without executing.
• Update docs/architecture.md with the decided interactive install entry point.

Context

Standalone install commands reduced coupling but increased cognitive load. Recent docs deprecated all-in-one admin install as opaque; this ADR reframes it as the guided entry point while keeping per-repo as the default path (ADR 0044).

Test plan

• make lint passes (ADR frontmatter, numbers, link scope)
• Review ADR Decision aligns with existing standalone command split (feat(cli): add github sub-command for standalone org/repo setup #1259, feat(cli): add mint sub-command for standalone GCP mint management #1261, docs: deprecate all-in-one admin, restructure reference/ into sidebar sections #2698)
• Confirm ADR 0066 number does not collide with in-flight ADRs (docs(adr): add ADR 0063 for ready-made configuration presets #2743, docs(adr): add ADR 0065 for human-gated permission adjustments #2830)

Made with Cursor

[fullsend-ai-review]

🤖 Review · ⚠️ Cancelled · Started 10:52 AM UTC · Ended 11:03 AM UTC
Commit: 0a95cac · View workflow run →

[qodo-code-review]

PR Summary by Qodo

Add ADR 0066: guided interactive admin install orchestrator

📝 Documentation 🕐 10-20 Minutes

AI Description

• Add ADR 0066 documenting admin install as an interactive installation orchestrator.
• Define a versioned YAML decision tree driving both CLI guidance and future agent skills.
• Update architecture docs to reference the new guided install entry point.

Diagram

graph TD
  H(["Human operator"]) --> CLI["`admin install` (CLI)"] --> PH["Phase commands (mint/github/inference/repos)"] --> EXT{{"GitHub/GCP/Infra"}}
  A(["Agent" ]) --> SK["Install-guidance skill"] --> TREE[["Decision tree (YAML)" ]] --> CLI

  subgraph Legend
    direction LR
    _actor(["Actor" ]) ~~~ _svc["Command/service" ] ~~~ _art[["Versioned artifact" ]] ~~~ _ext{{"External"}}
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Keep standalone commands only (docs-only guidance)

• ➕ No interactive orchestration to maintain
• ➕ Lowest CLI surface area and fewer implicit behaviors
• ➖ High cognitive load and higher onboarding error rate
• ➖ Hard for agents to give bounded, consistent guidance without a shared decision model

2. New top-level command (e.g., `fullsend install`)

• ➕ Clean slate; avoids legacy expectations tied to admin install
• ➕ Can be designed purely around guided orchestration semantics
• ➖ Adds another entry point and more docs to maintain
• ➖ Loses familiarity of the established admin install mental model

3. Web/UI installer consuming a normative spec

• ➕ Potentially best UX and easiest branching visualization
• ➕ Naturally shareable for both humans and automation
• ➖ Higher upfront scope and delivery risk
• ➖ Requires a stricter contract (normative spec) and compatibility guarantees earlier

Recommendation: The ADR’s chosen approach—reviving admin install as an interactive orchestrator backed by a versioned YAML decision tree—is a good middle ground: it reduces adopter/agent cognitive load while keeping the existing standalone commands as the stable execution layer. Deferring a normative spec until there’s a second consumer is reasonable, as long as the YAML schema is documented and tested alongside the artifact.

Files changed (2) +109 / -0

Documentation (2) +109 / -0

0066-interactive-admin-install-guide.mdAdd ADR 0066 defining guided interactive 'admin install' +108/-0

Add ADR 0066 defining guided interactive 'admin install'

• Introduces a new accepted ADR describing 'admin install' as an interactive, TTY-driven orchestrator that delegates to existing 'mint'/'github'/'inference'/'repos' phases. Specifies a versioned YAML decision tree shared by the CLI and future agent install-guidance skills, including '--guided' and '--plan' behaviors and coverage expectations.

docs/ADRs/0066-interactive-admin-install-guide.md

architecture.mdDocument 'admin install' as the interactive install entry point +1/-0

Document 'admin install' as the interactive install entry point

• Adds an architecture bullet linking to ADR 0066 and positioning 'admin install' as the guided orchestrator over existing installation phases rather than a monolithic provisioner.

docs/architecture.md

[github-actions]

Site preview

Preview: https://46b83fee-site.fullsend-ai.workers.dev

Commit: 59b0509f70d9e03608e6e76a4192375b8d190150

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📜 Skill insights (1)

Context used

✅ Compliance rules (platform): 54 rules

✅ Skills: writing-user-docs, writing-adrs

1. Admin install docs conflict ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

docs/architecture.md now presents admin install as the guided install entry point, but other docs
still label fullsend admin install as deprecated and recommend avoiding it, which will confuse
readers about the recommended workflow. This should be reconciled to reflect ADR 0066’s nuance
(deprecated as opaque monolith, not as guided orchestrator).

Code

docs/architecture.md[50]

+- 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)).

Relevance

⭐⭐⭐ High

Team often reconciles doc drift; PR 2698 updated docs to avoid conflicting admin-install guidance.

PR-#2698
PR-#2334

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The PR adds an architecture bullet stating admin install is the guided orchestrator, but existing
install docs still tell users that fullsend admin install / admin install is deprecated and
recommend using standalone commands instead, without the ADR 0066 clarification. This inconsistency
is new/heightened because the architecture doc is intended to be the "current truth" and will be
read as authoritative guidance.

docs/architecture.md[38-51]
docs/guides/infrastructure/advanced-setup.md[188-190]
docs/guides/dev/cli-internals.md[99-102]
docs/ADRs/0066-interactive-admin-install-guide.md[99-104]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`docs/architecture.md` now asserts that `admin install` is the guided interactive entry point, but other documentation still describes `fullsend admin install` / `admin install` as deprecated in a way that reads like it should not be used at all. This creates conflicting guidance across docs.

## Issue Context
ADR 0066 reframes the deprecation: the old *monolithic provisioner* behavior is deprecated, while `admin install` is intended to exist as a guided orchestrator over standalone phases. The docs that mention deprecation should be updated to reflect that nuance and link to ADR 0066.

## Fix Focus Areas
- docs/guides/infrastructure/advanced-setup.md[188-190]
- docs/guides/dev/cli-internals.md[101-102]
- docs/architecture.md[47-51]

## Suggested changes
- Update the “Deprecated” callouts to explicitly say the *all-in-one/monolithic provisioner* mode is deprecated, not the `admin install` entry point concept.
- Add a short cross-reference to ADR 0066 in those sections.
- If the guided orchestrator is not yet implemented, add a clarifying sentence indicating this is the accepted direction and follow-on implementation work, so readers don’t assume the interactive flow already exists.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. ADR 0066 multiple decisions 📜 Skill insight ⚙ Maintainability

Description

The ## Decision section contains six distinct decisions (interactive behavior, command flags,
published YAML tree, coverage requirements, agent skill behavior, and normative-spec deferral). This
violates the requirement that each ADR record exactly one decision, making future change tracking
and supersession ambiguous.

Code

docs/ADRs/0066-interactive-admin-install-guide.md[R60-95]

+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)).

Relevance

⭐ Low

Repo ADRs routinely use multi-item “## Decision” lists (e.g., ADR 0059) and accept them.

PR-#1580

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

PR Compliance ID 1062089 requires each ADR to record exactly one decision. In ADR 0066, the `##
Decision section is a numbered list of six separate decisions (items 1 through 6`), indicating
multiple decisions are being made in a single ADR.

docs/ADRs/0066-interactive-admin-install-guide.md[58-96]
Skill: writing-adrs

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`docs/ADRs/0066-interactive-admin-install-guide.md` records multiple distinct decisions in its `## Decision` section (items 1-6). The ADR must be narrowed to exactly one decision, with other decisions moved to separate ADRs or rephrased as consequences/implementation notes.

## Issue Context
Compliance requires one decision per ADR so acceptance/supersession is unambiguous.

## Fix Focus Areas
- docs/ADRs/0066-interactive-admin-install-guide.md[58-96]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 11:03 AM UTC · Completed 11:16 AM UTC
Commit: 8da72c5 · View workflow run →

[fullsend-ai-review]

Review

Findings

Low

• [missing-context-reference] docs/ADRs/0044-deprecate-per-org-installation-mode.md — ADR 0044 deprecates per-org mode and mentions admin install <org> removal, while new ADR 0066 revives admin install as a guided orchestrator. A cross-reference annotation from ADR 0044 to ADR 0066 would clarify the distinction, though the two ADRs are compatible (0044 deprecates per-org mode, 0066 reframes the command). ADR 0066 already references ADR 0044 in its Decision section.
  Remediation: Add a minor annotation to ADR 0044 cross-referencing ADR 0066.

• [architectural-coherence] docs/ADRs/0066-interactive-admin-install-guide.md — ADR 0066 references ADR 0044 in the Decision section body text ("Per-org mode remains a deprecated branch per ADR 0044") but does not include it in relates_to frontmatter. Note: relates_to uses topic labels (e.g., agent-infrastructure), not ADR references, so adding an ADR number would be inconsistent with the schema convention. The body cross-reference is sufficient.

• [outdated-deprecation-guidance] docs/guides/getting-started/org-mode.md:6 — The deprecation notice references only ADR 0044 without mentioning ADR 0066's accepted direction for reviving admin install as a guided orchestrator. Users reading this page may not realize the command itself is not deprecated — only per-org mode is.
  Remediation: Update the deprecation notice to distinguish between deprecated per-org mode (ADR 0044) and the accepted interactive orchestrator direction (ADR 0066).

• [potentially-stale-reference] docs/plans/deprecate-per-org-install.md:88 — The deprecation plan directs users to fullsend admin install <owner/repo>, which remains correct guidance. No update needed until the ADR 0066 orchestrator implementation begins.

Previous run

Review

Findings

Low

• [architectural-coherence] docs/ADRs/0066-interactive-admin-install-guide.md — ADR 0066 proposes reviving admin install as an interactive guided orchestrator, but does not explicitly cross-reference ADR 0044 (which deprecates per-org installation mode) to clarify the relationship. The ADR's Context section acknowledges the deprecation of the monolithic path, and the updated docs in this PR correctly distinguish between deprecated monolithic mode and the accepted guided entry point. However, adding a direct cross-reference to ADR 0044 in the Status or Context section would make the relationship between the two decisions more discoverable.
  Remediation: Consider adding ADR 0044 to the relates_to frontmatter or adding a brief note in the Context section clarifying that ADR 0044 deprecates per-org mode (not the admin install command itself), and this ADR reframes the command as a guided orchestrator over per-repo standalone phases.

---

Labels: PR adds a new ADR about the install entry point and updates installation documentation

[fullsend-ai-review]

🤖 Review · ❌ Terminated · Started 7:32 AM UTC · Ended 7:49 AM UTC
Commit: e8381e3 · View workflow run →

[ifireball]

Addressed the Qodo docs-conflict finding in 8da72c5 (reconcile monolithic deprecation vs ADR 0066 guided orchestrator in advanced-setup.md and cli-internals.md) and rebased onto current main in 59b0509f (resolved docs/architecture.md merge conflict — kept both ADR 0066 and ADR 0067 bullets). CI is green on the latest commit.

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 7:32 AM UTC · Completed 7:49 AM UTC
Commit: 59b0509 · View workflow run →