agnes-the-ai-analyst/app/web/setup_instructions.py

"""Single source of truth for the "Setup a new Claude Code" clipboard payload.

Both the JS-embedded clipboard renderer (`_claude_setup_instructions.jinja`)
and the read-only HTML preview on the dashboard and /install pages consume
these lines. Keep it in Python so there is exactly ONE place that edits.

Placeholders `{server_url}`, `{token}`, `{wheel_filename}`, and `{server_host}`
are substituted at render time. `{wheel_filename}` and `{server_host}` are
pre-substituted server-side via `resolve_lines()`; `{server_url}` and
`{token}` survive into the JS template and are filled in at click time.

`{wheel_filename}` is server-pre-substituted because `uv tool install`
validates the PEP 427 filename *in the URL path* before fetching, so a
stable alias like `agnes.whl` fails with "Must have a version" — we need
the real versioned filename inlined.

`{server_host}` is server-pre-substituted because the `git config` and
`claude plugin marketplace add` lines need the bare host (no scheme), and
the click-time JS only knows the full origin (`{server_url}`).

## Cross-platform trust strategy (when `ca_pem` is supplied)

The trust block (step 0) is the load-bearing piece. Three things bit us in
practice and the design here exists to dodge each one:

1. **rustls rejects the Agnes leaf cert as `CaUsedAsEndEntity`.** The Agnes
   server's self-signed cert is simultaneously its own CA (basicConstraints
   `CA:TRUE`) AND the leaf served on the wire — a setup OpenSSL tolerates
   but webpki/rustls strictly refuses. So `uv tool install <https-url>`
   never works against the Agnes wheel endpoint. We download the wheel via
   curl first (curl uses OpenSSL, accepts the cert), then `uv tool install
   --native-tls --force <local-file>` lets rustls reuse the OS trust store
   for PyPI dependency resolution. No HTTPS hop through rustls touches the
   Agnes host.

2. **`SSL_CERT_FILE` REPLACES the trust store, it doesn't append.** Pointing
   it at `~/.agnes/ca.pem` alone breaks every Python tool that needs to
   reach a public host (PyPI, GitHub) — `da` works fine because it only
   talks to Agnes, but `uv run --with <pkg>` immediately fails with
   `UnknownIssuer`. We materialize a combined bundle at
   `~/.agnes/ca-bundle.pem` (system roots + Agnes CA) and point all
   `SSL_CERT_FILE` / `REQUESTS_CA_BUNDLE` / `GIT_SSL_CAINFO` at it.
   `NODE_EXTRA_CA_CERTS` keeps pointing at just `ca.pem` because Node's
   semantics is *additive* (appends to bundled roots), so a single-cert
   file is correct there.

3. **Bun-compiled `claude` (Windows + macOS distributions) ignores every
   CA env var AND the OS trust store for marketplace HTTPS.** On macOS
   arm64 the binary at `~/.local/bin/claude` is a Mach-O with a `__BUN`
   segment (single-file `bun build --compile`); on Windows claude.exe is
   the same shape. `strings` shows the binary recognizes
   `NODE_EXTRA_CA_CERTS`, `SSL_CERT_FILE`, `REQUESTS_CA_BUNDLE`,
   `CURL_CA_BUNDLE` (including a "NODE_EXTRA_CA_CERTS detected" log
   string), but in practice the values never reach the TLS context — a
   known limitation of Bun's compiled-binary HTTPS path. Registering the
   cert in the OS trust store (Windows: `certutil -user -addstore Root`;
   macOS: `security add-trusted-cert`; Linux: `update-ca-certificates` /
   `update-ca-trust`) doesn't fix it on Windows or macOS either — the
   binary's bundled CA list isn't refreshable from the OS store.

   So the marketplace step always uses system `git clone` regardless of
   platform — system git honors `GIT_SSL_CAINFO` from the combined bundle
   in step 0(d). We tried having Linux attempt direct HTTPS first (where
   node-based claude DOES respect `NODE_EXTRA_CA_CERTS`), but `claude
   plugin marketplace add <https-url>` is broken end-to-end on every
   distribution: it does succeed at downloading the marketplace.json, but
   stores it as a single file. The plugin entries' `source: "./plugins/<name>"`
   paths are then resolved as local filesystem paths against that file's
   parent dir — and the plugin tree obviously isn't there. Only the clone
   path produces a real directory tree that `plugin install` can read.

   The OS trust-store registration in (c) is still done on all three
   platforms because it's needed for *non-claude* native tools — e.g.
   the system git fetch path itself (Schannel on Windows, Security
   framework on macOS) trusts via the OS store, not via env vars.

   Marketplace refresh: after the initial clone, `agnes refresh-marketplace`
   incrementally `git pull`s against the same clone and runs `claude plugin
   marketplace update agnes`. Credentials are injected per-pull via a
   one-shot git credential helper (PAT from `~/.config/agnes/token.json`)
   so the cloned repo's `origin` URL stays PAT-free at rest. The
   SessionStart hook (installed by `agnes init`) calls refresh-marketplace
   on every Claude Code session so changes server-side propagate
   automatically.

## Step ordering

The numbered steps are arranged so that:
  - All installation work (CLI, plugins) happens first, in one go.
  - `agnes init` is mandatory — it bundles auth, workspace bootstrap,
    CLAUDE.md fetch, and Claude Code SessionStart/End hooks into one
    non-interactive call. Replaces the old `agnes auth import-token` +
    `agnes auth whoami` pair.
  - `agnes diagnose` runs late so it doubles as a final smoke test after
    plugins are in place, instead of gating them. It is also the last
    step before Confirm — the whole prompt is non-interactive, no
    decision questions for the user.

Layout:
  0  TLS trust block (only when ca_pem is supplied)
  1  Install CLI
  2  agnes init (auth + workspace bootstrap)
  3  agnes catalog (smoke verify)
  4  Pre-flight: git + claude
  5  Marketplace (always, even with empty served stack)
  6  MCP servers (Atlassian Remote MCP)
  7  Diagnose
  8  Confirm

The combined-bundle source uses a fallback chain so the prompt still works
on machines without the system Python `certifi`: we try (a) `python3 -c
'import certifi'`, (b) the platform's curl/openssl bundle path, (c)
`uv run --with certifi` as a network last-resort. The user explicitly
permitted that fallback chain — it's not improvising-around-a-TLS-error.
"""

from __future__ import annotations

# Marketplace name as published by app.marketplace_server.packager.
# Hard-coded here (rather than imported) to keep this module dependency-free
# and trivially testable. If the value ever drifts, the regression test
# below catches it.
_MARKETPLACE_NAME = "agnes"


def _tls_trust_block(ca_pem: str) -> list[str]:
    """Step 0 — cross-platform TLS trust bootstrap for the Agnes server.

    Emitted only when the server has a non-publicly-trusted cert. Does four
    things in a single numbered block (see module docstring for the full
    rationale):

      (a) Detect platform (Windows Git Bash / macOS / Linux) and pick the
          shell rc file that the user's login shell actually reads.
          `$SHELL`-driven, NOT existence-of-rc-driven — old setups put a
          legacy `.bashrc` next to a default zsh shell on macOS, and the
          `[ -f .bashrc ]` heuristic silently writes to the wrong file.
      (b) Write the cert PEM to `~/.agnes/ca.pem` via single-quoted heredoc
          (so `$` / backtick chars in real-world certs never shell-expand).
      (c) Register the cert in the OS trust store (so native binaries that
          bypass our env vars — claude.exe, system git's Schannel backend,
          Python apps using `truststore` — still trust the host).
          Idempotent: re-running just re-affirms the entry.
      (d) Build a *combined* CA bundle (system roots + Agnes CA) at
          `~/.agnes/ca-bundle.pem`, with a fallback chain for the system
          roots source. Persist `SSL_CERT_FILE` / `REQUESTS_CA_BUNDLE` /
          `GIT_SSL_CAINFO` pointing at the bundle, plus
          `NODE_EXTRA_CA_CERTS` pointing at just `ca.pem` (Node
          appends-not-replaces). Persistence is idempotent via a grep
          guard for the `AGNES_CA_PEM_TRUST` marker.
    """
    pem = ca_pem.strip()
    lines: list[str] = [
        "0) Trust the Agnes TLS certificate — cross-platform setup for a self-signed / private-CA host.",
        "",
        "   (a) Detect platform + pick the shell rc file your login shell actually reads.",
        "       Driven by $SHELL + uname (NOT by which rc files happen to exist on disk).",
        "",
        "       case \"$(uname -s)\" in",
        "         Darwin)               PLATFORM=macos ;;",
        "         Linux)                PLATFORM=linux ;;",
        "         MINGW*|MSYS*|CYGWIN*) PLATFORM=windows ;;",
        "         *) echo \"Unsupported OS: $(uname -s)\" >&2; exit 1 ;;",
        "       esac",
        "       SHELL_NAME=\"$(basename \"${SHELL:-bash}\")\"",
        "       case \"${SHELL_NAME}:${PLATFORM}\" in",
        "         zsh:*)                   RC=\"$HOME/.zshrc\" ;;",
        "         bash:macos)              RC=\"$HOME/.bash_profile\" ;;",
        "         bash:windows|bash:linux) RC=\"$HOME/.bashrc\" ;;",
        "         *)                       RC=\"$HOME/.profile\" ;;",
        "       esac",
        "       echo \"Platform: $PLATFORM, shell: $SHELL_NAME, rc: $RC\"",
        "",
        "   (b) Write the cert (single-quoted heredoc so $/backticks in the body don't expand):",
        "",
        "       mkdir -p ~/.agnes",
        "       cat > ~/.agnes/ca.pem <<'AGNES_CA_PEM'",
    ]
    # PEM body is flush-left: `<<'DELIM'` heredocs preserve leading whitespace,
    # and any indent inside the cert breaks `openssl x509` / Python ssl parsers.
    lines.extend(pem.splitlines())
    lines.extend([
        "AGNES_CA_PEM",
        "",
        "   (c) Register the cert in the OS trust store. Native binaries (claude.exe,",
        "       system git's Schannel/Security.framework backends) read the OS store",
        "       and ignore our env vars — without this, the later marketplace `git",
        "       clone` (when plugins are configured) and any user-side git/native",
        "       tooling against the Agnes host will fail.",
        "       No admin rights needed (user-store only). Idempotent.",
        "",
        "       case \"$PLATFORM\" in",
        "         windows)",
        "           WIN_CA=\"$(cygpath -w ~/.agnes/ca.pem)\"",
        "           certutil.exe -user -addstore \"Root\" \"$WIN_CA\"",
        "           ;;",
        "         macos)",
        "           # Will prompt once for the keychain password.",
        "           security add-trusted-cert -r trustRoot \\",
        "             -k \"$HOME/Library/Keychains/login.keychain-db\" \\",
        "             ~/.agnes/ca.pem",
        "           ;;",
        "         linux)",
        "           if command -v update-ca-certificates >/dev/null 2>&1; then",
        "             sudo cp ~/.agnes/ca.pem /usr/local/share/ca-certificates/agnes.crt",
        "             sudo update-ca-certificates",
        "           elif command -v update-ca-trust >/dev/null 2>&1; then",
        "             sudo cp ~/.agnes/ca.pem /etc/pki/ca-trust/source/anchors/agnes.crt",
        "             sudo update-ca-trust",
        "           else",
        "             echo \"WARN: install ~/.agnes/ca.pem into your distro's trust store manually\" >&2",
        "           fi",
        "           ;;",
        "       esac",
        "",
        "   (d) Build a COMBINED CA bundle (system roots + Agnes CA) for Python tools",
        "       and curl. SSL_CERT_FILE *replaces* the trust store, so pointing it at",
        "       the Agnes CA alone would break public hosts (PyPI etc.). Source the",
        "       system roots from a fallback chain — the first source that produces",
        "       a non-empty, existing path wins. Don't abort on the first miss; that's",
        "       what the chain is for.",
        "",
        "       CERTIFI_PATH=\"$(python3 -c 'import certifi; print(certifi.where())' 2>/dev/null || true)\"",
        "       [ -z \"$CERTIFI_PATH\" ] && CERTIFI_PATH=\"$(python -c 'import certifi; print(certifi.where())' 2>/dev/null || true)\"",
        "       if [ -z \"$CERTIFI_PATH\" ]; then",
        "         for p in /mingw64/ssl/certs/ca-bundle.crt /usr/ssl/certs/ca-bundle.crt \\",
        "                  /etc/ssl/certs/ca-certificates.crt /etc/pki/tls/certs/ca-bundle.crt \\",
        "                  /etc/ssl/cert.pem; do",
        "           [ -f \"$p\" ] && CERTIFI_PATH=\"$p\" && break",
        "         done",
        "       fi",
        "       if [ -z \"$CERTIFI_PATH\" ]; then",
        "         CERTIFI_PATH=\"$(uv run --native-tls --with certifi --no-project python -c 'import certifi; print(certifi.where())' 2>/dev/null || true)\"",
        "       fi",
        "       if [ -z \"$CERTIFI_PATH\" ] || [ ! -f \"$CERTIFI_PATH\" ]; then",
        "         echo \"ERROR: locate a system CA bundle. Install Python 3 + certifi and re-run.\" >&2",
        "         exit 1",
        "       fi",
        "       echo \"Base CA bundle: $CERTIFI_PATH\"",
        "       cat \"$CERTIFI_PATH\" ~/.agnes/ca.pem > ~/.agnes/ca-bundle.pem",
        "",
        "   (e) Persist env vars in the rc file picked in (a). Idempotent — won't",
        "       duplicate on re-run thanks to the AGNES_CA_PEM_TRUST grep guard.",
        "       Note the asymmetry: SSL_CERT_FILE (and REQUESTS_CA_BUNDLE, GIT_SSL_CAINFO)",
        "       point at the COMBINED bundle because those tools REPLACE trust.",
        "       NODE_EXTRA_CA_CERTS points at just ca.pem because Node APPENDS to its",
        "       bundled roots.",
        "",
        "       if ! grep -q 'AGNES_CA_PEM_TRUST' \"$RC\" 2>/dev/null; then",
        "         cat >> \"$RC\" <<'AGNES_RC_BLOCK'",
        "# AGNES_CA_PEM_TRUST — added by Agnes setup",
        "# Combined bundle (system roots + Agnes CA) for tools that REPLACE trust:",
        "export SSL_CERT_FILE=\"$HOME/.agnes/ca-bundle.pem\"",
        "export REQUESTS_CA_BUNDLE=\"$HOME/.agnes/ca-bundle.pem\"",
        "export GIT_SSL_CAINFO=\"$HOME/.agnes/ca-bundle.pem\"",
        "# Single-cert file for Node (APPENDS to bundled roots):",
        "export NODE_EXTRA_CA_CERTS=\"$HOME/.agnes/ca.pem\"",
        "export PATH=\"$HOME/.local/bin:$PATH\"",
        "AGNES_RC_BLOCK",
        "       fi",
        "       # Apply for THIS shell too:",
        "       export SSL_CERT_FILE=\"$HOME/.agnes/ca-bundle.pem\"",
        "       export REQUESTS_CA_BUNDLE=\"$HOME/.agnes/ca-bundle.pem\"",
        "       export GIT_SSL_CAINFO=\"$HOME/.agnes/ca-bundle.pem\"",
        "       export NODE_EXTRA_CA_CERTS=\"$HOME/.agnes/ca.pem\"",
        "       export PATH=\"$HOME/.local/bin:$PATH\"",
        "",
        "   IMPORTANT for the Bash tool: env vars do NOT persist between separate",
        "   Bash invocations. Re-export the four lines above (SSL_CERT_FILE,",
        "   REQUESTS_CA_BUNDLE, GIT_SSL_CAINFO, NODE_EXTRA_CA_CERTS) plus PATH at",
        "   the top of every later step's bash block that talks to Agnes.",
        "",
    ])
    return lines


def _install_cli_lines(*, has_ca: bool, server_url_placeholder: str = "{server_url}") -> list[str]:
    """Step 1 — install the `agnes` CLI.

    When the trust block was emitted (`has_ca=True`), we MUST avoid
    `uv tool install <https-url>` against the Agnes wheel endpoint:
    rustls rejects the Agnes leaf cert with `CaUsedAsEndEntity`, regardless
    of `--native-tls` (the rejection is at chain validation, not at trust
    lookup — putting the cert in the OS store doesn't fix it). Solution:
    download the wheel with `curl --cacert` (curl uses OpenSSL, no rustls),
    then `uv tool install --native-tls` from the local file. PyPI deps
    still resolve over HTTPS, but `--native-tls` makes uv use the OS trust
    store for that path, which is fine because PyPI's CA chain is public.

    When `has_ca=False`, we trust the server's cert is publicly valid, so
    the simple direct install works.
    """
    if has_ca:
        return [
            "1) Install the CLI.",
            "   The Agnes server's self-signed cert trips rustls' CaUsedAsEndEntity check,",
            "   so direct `uv tool install <https-url>` against the wheel endpoint fails",
            "   (even with --native-tls). Workaround: curl-then-local-install.",
            "",
            "   If uv is missing first:",
            "     curl -LsSf https://astral.sh/uv/install.sh | sh",
            "     export PATH=\"$HOME/.local/bin:$PATH\"",
            "",
            "   WHEEL=/tmp/{wheel_filename}",
            f"   curl -fsSL --cacert ~/.agnes/ca.pem -o \"$WHEEL\" {server_url_placeholder}/cli/wheel/{{wheel_filename}}",
            "   uv tool install --native-tls --force \"$WHEEL\"",
            "",
            "   If `agnes --version` fails after install because ~/.local/bin is not on PATH:",
            "     export PATH=\"$HOME/.local/bin:$PATH\"",
            "     # Persist for future shells. Use `grep -qF` (fixed-string,",
            "     # not regex) + `||` short-circuit so a re-run doesn't append",
            "     # a duplicate. Pick the rc file your login shell reads:",
            "     RC=\"$HOME/.zshrc\"  # or ~/.bashrc / ~/.bash_profile",
            "     grep -qF '$HOME/.local/bin' \"$RC\" 2>/dev/null \\",
            "       || echo 'export PATH=\"$HOME/.local/bin:$PATH\"' >> \"$RC\"",
            "     # (The trust block in step 0 already does this for you on first run.)",
        ]
    return [
        "1) Install the CLI:",
        f"   uv tool install --force {server_url_placeholder}/cli/wheel/{{wheel_filename}}",
        "",
        "   If uv is not installed yet:",
        "     curl -LsSf https://astral.sh/uv/install.sh | sh",
        "",
        "   If `agnes --version` fails after install because ~/.local/bin is not on PATH:",
        "     export PATH=\"$HOME/.local/bin:$PATH\"",
        "     # Persist for future shells. Use `grep -qF` (fixed-string, not",
        "     # regex) + `||` short-circuit so a re-run doesn't append a",
        "     # duplicate. Pick the rc file your login shell reads:",
        "     RC=\"$HOME/.zshrc\"  # or ~/.bashrc / ~/.bash_profile",
        "     grep -qF '$HOME/.local/bin' \"$RC\" 2>/dev/null \\",
        "       || echo 'export PATH=\"$HOME/.local/bin:$PATH\"' >> \"$RC\"",
    ]


def _init_lines(server_url_placeholder: str = "{server_url}") -> list[str]:
    """Steps 2-4 — workspace folder check, then `agnes init` + smoke verify.

    Step 2 verifies the user is already cd'd into the workspace folder
    that the /home onboarding page's visible "Step 2 — create your
    workspace folder" told them to create manually (`mkdir -p
    ~/{workspace_dir} && cd ~/{workspace_dir}`). The pasted script
    DOES NOT auto-create the folder — that would silently override an
    intentional choice to install at a different path (e.g. the user
    cd'd to `~/work/agnes-prod` on purpose). Instead we `pwd`, compare
    to `$HOME/{workspace_dir}`, and on mismatch warn loudly and ask the
    user to either re-paste from the right folder or explicitly confirm
    "install here" in the current cwd.

    `{workspace_dir}` and `{instance_brand}` are placeholders pre-substituted
    by :func:`resolve_lines` from the operator-configured brand. Defaults
    keep `~/Agnes` behavior for instances that don't set the brand knob.

    `agnes init --workspace .` continues to use the current cwd, so once
    step 2 has confirmed (or the user has explicitly accepted) the
    install dir, step 3 lands in the right place. Step 9's restart-claude
    cue references "this same directory" so users on a custom path see
    accurate guidance.

    `agnes init` is the workspace-rails delivery mechanism for everyone:
    it authenticates with the PAT, fetches CLAUDE.md (RBAC-filtered),
    writes AGNES_WORKSPACE.md (human-facing docs), installs Claude Code
    SessionStart/End hooks (auto-refresh), and runs an initial `agnes pull`
    so DuckDB views are ready. Subsumes the legacy `agnes auth import-token`
    + `agnes auth whoami` pair — `init` already verifies the PAT against
    `/api/catalog/tables` internally, and `agnes catalog` then doubles as
    a smoke verify of the data plane.

    The PAT minted by `/setup` is `general` scope with a 90 d TTL, so the
    init call will succeed for the operator's whole 90 d window without
    re-clicking "Generate prompt".
    """
    return [
        "",
        "2) Verify the user is already in the workspace folder.",
        "   The /home page's visible \"Step 2 — create your workspace folder\"",
        "   already asked the user to run",
        "       mkdir -p ~/{workspace_dir} && cd ~/{workspace_dir}",
        "   in their terminal BEFORE pasting this script. Do NOT silently",
        "   re-create the folder here — the user may have intentionally cd'd",
        "   to a different location to install {instance_brand} there instead.",
        "",
        "   Run:",
        "       pwd",
        "   Expected: $HOME/{workspace_dir}  (i.e. ~/{workspace_dir})",
        "",
        "   If `pwd` matches the expected path: continue silently to step 3.",
        "",
        "   If `pwd` does NOT match, STOP and tell the user verbatim:",
        "",
        "       \"You are in <current-pwd>, but {instance_brand} is normally",
        "       installed in ~/{workspace_dir} (see /home Step 2). Either run",
        "           mkdir -p ~/{workspace_dir} && cd ~/{workspace_dir}",
        "       in your terminal now and re-paste this setup script, OR reply",
        "       'install here' to install {instance_brand} in <current-pwd>",
        "       instead. Reply 'abort' to stop.\"",
        "",
        "   Wait for the user's reply.",
        "     - 'install here'  → continue to step 3 in the current cwd.",
        "                         The cwd you saw from `pwd` is the install",
        "                         directory; remember it for step 9.",
        "     - 'abort' / anything else → stop without making any changes.",
        "                         Do NOT run `mkdir`, do NOT `cd`, do NOT",
        "                         continue to step 3.",
        "",
        "3) Bootstrap your {instance_brand} workspace in this directory.",
        "   Write the PAT to a file FIRST, then run `agnes init` with",
        "   `--token-file`. Passing the JWT inline via `--token \"eyJ...\"`",
        "   sometimes trips Claude Code's auto-classifier (long bearer",
        "   token in a command line looks like a credential-exfil pattern);",
        "   piping the token through a file keeps it out of the command-",
        "   line argv entirely.",
        "",
        "   mkdir -p ~/.agnes && umask 077 && cat > ~/.agnes/token <<'AGNES_PAT'",
        "{token}",
        "AGNES_PAT",
        f"   agnes init --server-url \"{server_url_placeholder}\" --token-file ~/.agnes/token --workspace .",
        "",
        "   If Claude Code still blocks an `agnes` command (e.g. the",
        "   `agnes init` line above or `agnes catalog` in step 4), prefix",
        "   it with `!` to run the command directly in your shell,",
        "   bypassing the auto-classifier — e.g. `! agnes init …`. The",
        "   `!` prefix is Claude Code's escape hatch for commands you",
        "   explicitly trust.",
        "",
        "   This authenticates with the PAT, fetches your CLAUDE.md (RBAC-filtered),",
        "   writes AGNES_WORKSPACE.md (human-facing docs), installs Claude Code",
        "   SessionStart/End hooks (auto-refresh), and runs an initial `agnes pull`",
        "   so your DuckDB views are ready.",
        "",
        "4) Verify the data is queryable:",
        "   agnes catalog",
        "",
        "   This should list the tables your account has grants for. Empty list",
        "   means your admin hasn't granted you access yet — contact them.",
        "",
        "   Tip: type `/agnes-private` inside any Claude Code session to mark it",
        "   private — its transcript is skipped by `agnes push` (audit-logged to",
        "   `.claude/agnes-sessions-private-skipped.txt`). The statusbar shows",
        "   `🔒 agnes-private` while you're in a private session.",
    ]


def _diagnose_lines(*, diagnose_num: str) -> list[str]:
    """Diagnose step — runs AFTER the marketplace + MCP blocks.

    Putting it last (instead of right after `whoami`) means it doubles as
    a server-health smoke test that runs once everything else is in place,
    not as a gate before them.

    The bundled `agnes skills` knowledge base (markdown documents listable
    via `agnes skills list` / readable via `agnes skills show <name>`) is
    intentionally NOT surfaced as its own setup step (#242 dropped that
    interactive prompt). Discovery happens organically when CLAUDE.md or
    another skill references a specific entry (see the
    `agnes skills show agnes-data-querying` mention in the CLAUDE.md
    template's BigQuery section). Bulk-copying every skill into
    `~/.claude/skills/agnes/` at setup time was an opinion question with
    no obvious right answer; on-demand lookup is the one-size-fits-all
    default.
    """
    return [
        "",
        f"{diagnose_num}) Run diagnostics:",
        "   agnes diagnose",
        "",
        "   This should print \"Overall: healthy\". `db_schema: unknown` and",
        "   `data: 0 tables` are NORMAL in two cases:",
        "     - fresh install (no tables registered yet), and",
        "     - non-admin roles (e.g. `analyst`) that don't have grants to read",
        "       the system schema even on populated instances.",
        "   Only flag actual yellow/red checks (api / duckdb_state / users).",
    ]


def _connectors_block(
    step_num: str,
    connector_prompts: dict[str, str],
    *,
    confirm_step_num: str,
) -> list[str]:
    """Per-connector interactive ask + inline prompt. Last interactive
    step before Confirm.

    Defaults to install (Y) — the user has to actively type "no" to skip.
    Rationale: when the operator provisions a shared GWS OAuth app
    (AGNES_GWS_CLIENT_ID + AGNES_GWS_CLIENT_SECRET), the GWS path runs
    in ~2 minutes with zero GCP clickops; Asana + Atlassian only need
    the user's own API token from their respective developer consoles —
    which they need either way to use the tool. Default-install matches
    "wire everything up" — the common path.

    Each connector's prompt body comes verbatim from
    ``app/web/connector_prompts.py`` — same source the /home tile cards
    render, so editing one place updates both surfaces. The prompts
    themselves are idempotent (each has its own step-0 precheck) so
    re-runs short-circuit cleanly.

    Connectors are presented in the order they appear in the
    ``connector_prompts`` dict — the caller controls ordering by how
    they build the dict. Today that's asana → gws → atlassian, matching
    the /home tile order.
    """
    lines = [
        "",
        f"{step_num}) Connect the user's tools (last interactive ask before Confirm):",
        "",
        "   For each tool below, ask the user verbatim: \"Set up <NAME> now? (Y/n)\".",
        "   Treat empty/Enter as YES — the default is install. Only skip when the",
        "   user types an explicit \"no\" / \"n\" / \"skip\". Wait for each answer",
        "   before moving to the next. The prompts below are idempotent and",
        "   safe to re-run if anything goes sideways.",
        "",
    ]
    # Stable ordering — let the dict iteration order win (Python 3.7+ insertion-ordered).
    # Caller controls which connectors are present; we just iterate.
    sub_letters = "abcdefghij"
    for i, (slug, body) in enumerate(connector_prompts.items()):
        # Display name is sourced from the registry so the ask phrasing stays
        # in lockstep with what /home renders.
        from app.web.connector_prompts import CONNECTORS  # local import — avoids module-load cycles
        display = next((c.display_name for c in CONNECTORS if c.slug == slug), slug)
        desc = next((c.description for c in CONNECTORS if c.slug == slug), "")
        lines.append(f"   {sub_letters[i]}) {display} — {desc}")
        lines.append(f"      Ask: \"Set up {display} now? (Y/n)\"")
        lines.append("      If yes (default) — follow this inline prompt verbatim:")
        lines.append("")
        # Indent the prompt body two spaces so it visually nests under the
        # ask. Empty lines stay empty (no trailing whitespace).
        for body_line in body.split("\n"):
            lines.append(f"      {body_line}" if body_line else "")
        lines.append("")
    lines.extend([
        f"   After all asks (regardless of answers) continue to step {confirm_step_num}.",
    ])
    return lines


def _restart_claude_lines(step_num: str) -> list[str]:
    """Final 'restart Claude Code' instruction emitted immediately before
    Confirm. Marketplace plugins, MCP server registrations, and the
    SessionStart hooks installed during init only load on the next
    Claude Code session — without this step the user sits inside the
    setup session with stale state and re-discovers the requirement
    later. The marketplace step's trailer already mentions /exit
    + claude conditionally; this is the unconditional equivalent so
    every path (with or without plugins) ends on the same cue.
    """
    return [
        "",
        f"{step_num}) Restart Claude Code so every plugin, MCP server, and SessionStart hook installed above actually loads:",
        "   Tell me to type `/exit` (or close the Claude Code session entirely), then run `claude` again from this same directory — the install dir confirmed in step 2 (`~/{workspace_dir}` on the default path, or whatever cwd the user explicitly accepted with 'install here').",
        "   The next session boots with all marketplace plugins, every connector's keychain entries / OAuth grants, and the agnes-welcome + refresh-marketplace SessionStart hooks active. This is the last action before the Confirm summary — once I'm back in Claude Code, setup is complete.",
    ]


def _finale_lines(*, confirm_step_num: str, has_ca: bool) -> list[str]:
    """Final Confirm step. Bullets it asks the assistant to report on must
    only reference earlier steps that were actually emitted, otherwise the
    assistant either hallucinates an answer or asks the user about a
    non-existent step. The CA-bundle-source bullet only makes sense when
    the trust block ran (`has_ca`). The marketplace clone bullet is
    unconditional now — preflight + marketplace are always emitted (Fix B
    in the 2026-05-10 init-report response). Init + catalog + diagnose +
    skills + connectors + version always render, so their bullets are
    unconditional. The per-connector ✅/❌ bullet exploits the uniform
    output contract every connector prompt emits on its verify step —
    the assistant scans its own prior output for those markers instead
    of re-running probes."""
    bullets = [
        "   - `agnes --version` output",
        "   - First few lines of `agnes catalog` (tables you can see)",
        "   - Confirmation that `./CLAUDE.md` and `./AGNES_WORKSPACE.md` exist",
        "   - Confirmation that `./.claude/settings.json` contains SessionStart/End hooks",
        "   - The `agnes diagnose` overall status",
        "   - Whether skills were copied or left on-demand",
        "   - Confirmation that `~/.agnes/marketplace/.git/` exists "
        "(the marketplace clone) and that any granted plugins installed",
        "   - For each connector (Asana, Google Workspace, Atlassian): "
        "the verbatim ✅ or ❌ line that the connector's verify step "
        "emitted earlier in this session (e.g. `✅ Asana ready — connected "
        "as Vojtech Rysanek. 2 workspace(s) visible.` or `❌ Atlassian setup "
        "failed: ...`). If the user declined a connector, say declined.",
    ]
    if has_ca:
        bullets.append(
            "   - Which CA bundle source got picked in step 0(d) "
            "(system Python certifi / system curl bundle / uv-fetched)"
        )
    return [
        f"{confirm_step_num}) Confirm:",
        "   Tell me \"{instance_brand} workspace is ready\" and summarize:",
        *bullets,
    ]


def _preflight_block(step_num: str) -> list[str]:
    """Pre-flight check — runs before the marketplace clone.

    `claude plugin marketplace add` (and our git-clone fallback) shells out
    to `git`, AND the marketplace step calls `claude` itself, so a missing
    binary on either side fails the step with a confusing error. We check
    both here so the user gets a single clear "install X" message instead
    of debugging a downstream error.

    Cross-platform install commands cover the three supported workstation
    OSes:
      - macOS: Homebrew (`brew install git`). The Xcode CLT bundle also
        ships git; we prefer brew because it's non-interactive.
      - Windows: winget (`winget install --id Git.Git -e ...`). Bundled
        with Windows 10 1809+ and Windows 11; non-interactive with --silent.
      - Linux: apt or dnf, depending on distro family.

    For `claude` we point at the official platform installer docs rather
    than vendoring an install one-liner — Anthropic ships per-platform
    installers (npm on Linux, native binary on macOS/Windows) and the
    canonical instructions live at https://docs.claude.com/claude-code.

    `step_num` is parameterized because step ordering shifted between
    layouts (the marketplace block now runs before diagnose/skills, so
    preflight + marketplace are steps 4-5 instead of 6-7).
    """
    return [
        "",
        f"{step_num}) Make sure git and claude are installed (required for the marketplace clone):",
        "     git --version",
        "     claude --version",
        "",
        "   If `git --version` fails (\"command not found\" or similar), install git:",
        "     - macOS:   brew install git",
        "     - Windows: winget install --id Git.Git -e --source winget --silent",
        "     - Linux:   sudo apt-get install git    OR    sudo dnf install git",
        "",
        "   If `claude --version` fails, install Claude Code:",
        "     - npm (Linux): npm i -g @anthropic-ai/claude-code",
        "     - macOS / Windows native installer: see https://docs.claude.com/claude-code",
        "",
        "   Then re-run both `--version` checks to confirm before continuing.",
    ]


def _marketplace_block(
    plugin_install_names: list[str],
    step_num: str,
) -> list[str]:
    """Build the marketplace + plugin-install block.

    `plugin_install_names` may be empty: registering the per-user
    marketplace clone with Claude Code is useful even when the operator
    has zero plugin grants, because it pre-wires the SessionStart hook
    and the grant flow — admin grants land on the next Claude Code
    session without re-running setup. The block copy adapts for the
    empty case so the comment-bullet doesn't promise plugin installs
    that won't happen.

    `step_num` is parameterized because step ordering shifted between
    layouts (this block now runs before diagnose/skills, so it's step 5
    instead of the old step 7).

    The whole block is one CLI invocation: ``agnes refresh-marketplace
    --bootstrap``. The CLI handles clone + PAT-strip + chmod + register-
    with-Claude + auto-install-from-manifest internally. This is what
    used to be a 15-line shell sequence inline; pulling it into the CLI
    bought:

      1. **Claude Code permission gate friendliness.** The agent-driven
         onboarding flow inside Claude Code denies ``rm -rf`` by default;
         the inline script tripped on it. Wrapping the destructive prep
         inside agnes lets the CLI's already-trusted permission grant
         cover it (Python ``shutil.rmtree`` doesn't pattern-match the
         shell ``rm -rf`` block).
      2. **Idempotence without inline ``rm``.** Re-running the install
         prompt over an existing clone now does fetch+reset under the
         hood (no destructive cleanup needed). The prompt's "safe to
         re-run" promise holds without forcing the operator to delete
         anything by hand.
      3. **One source of truth.** ``agnes refresh-marketplace`` is also
         the SessionStart hook command, so install + refresh share the
         same code path — version-aware reconcile, hook JSON output,
         credential helper PAT injection, all consistent.

    Why always clone (with the CLI doing it) instead of trying direct
    HTTPS marketplace add first? ``claude plugin marketplace add
    <https-url>`` does succeed against our ``/marketplace.git/`` endpoint
    (returns 200 + JSON), but Claude Code stores the response as a
    single-file marketplace and resolves plugin ``source:
    "./plugins/<name>"`` paths as local filesystem refs — so the
    subsequent ``claude plugin install`` looks for plugin trees at
    ``<marketplace-dir>/plugins/<name>/`` and 404s because the dir is a
    file. Only the git-clone path produces a real directory tree with
    plugin contents in place. Broken end-to-end on every Claude Code
    distribution; cloning is the only reliable install path.

    TLS handling for the in-binary ``git clone`` is fully covered by the
    cross-platform trust block (step 0) when the server's cert needs
    bootstrapping (`ca_pem` non-empty), and by the OS trust store when
    the cert is publicly-trusted. There used to be a legacy fallback
    here that emitted a host-scoped ``git config http.<host>.sslVerify
    false`` line for the ``AGNES_DEBUG_AUTH`` path; that's gone — it
    masked operator misconfigurations (a ``self_signed_tls=True``
    instance without ``/data/state/certs/fullchain.pem`` on disk) and
    its ``sslVerify=false`` shell command tripped Claude Code auto-mode
    classifiers. Operators serving a self-signed or private-CA cert
    must place the fullchain at ``AGNES_TLS_FULLCHAIN_PATH`` (default
    ``/data/state/certs/fullchain.pem``) so step 0 can read it via
    ``_read_agnes_ca_pem``.
    """
    has_plugins = bool(plugin_install_names)
    header = (
        "Register the Agnes Claude Code marketplace and install plugins:"
        if has_plugins
        else "Register the Agnes Claude Code marketplace (no plugins granted yet):"
    )
    bullet_5 = (
        "   #   5. install every plugin listed in the served manifest"
        if has_plugins
        else "   #   5. (no plugins to install — your account has zero grants)"
    )
    if has_plugins:
        trailer = [
            "   These run non-interactively. After they finish, tell the user to /exit",
            "   and run `claude` again so the new plugins load. From then on, the",
            "   SessionStart hook keeps the marketplace clone in sync via",
            "   `agnes refresh-marketplace --quiet` on every Claude Code session.",
        ]
    else:
        trailer = [
            "   Your account has no plugin grants right now, but registering the",
            "   marketplace anyway pre-wires the SessionStart hook. When an admin",
            "   grants you a plugin later, `agnes refresh-marketplace` (run by the",
            "   hook on every Claude Code session) will install it automatically —",
            "   no need to re-run this setup script.",
        ]
    return [
        "",
        f"{step_num}) {header}",
        "   # `agnes refresh-marketplace --bootstrap` does:",
        "   #   1. clone the per-user marketplace bare repo to ~/.agnes/marketplace",
        "   #   2. strip the PAT from the cloned origin URL (refreshes use a",
        "   #      per-invocation git credential helper, not the URL)",
        "   #   3. best-effort chmod 700/600 on POSIX (no-op on Windows NTFS)",
        "   #   4. `claude plugin marketplace add ~/.agnes/marketplace`",
        bullet_5,
        "   # Idempotent — re-runs over an existing clone do fetch+reset+reconcile",
        "   # via the same path the SessionStart hook uses.",
        "   agnes refresh-marketplace --bootstrap || {",
        "     echo \"ERROR: agnes refresh-marketplace --bootstrap failed\" >&2",
        "     exit 1",
        "   }",
        "",
        *trailer,
    ]




def _preamble_lines(*, has_ca: bool) -> list[str]:
    """Header that opens the prompt before the numbered steps. The
    `step 0(d) fallback chain` reference is only emitted when the trust
    block actually exists (`has_ca`); without it the line points at a
    non-existent step. The "don't disable TLS verification" advice itself
    stays unconditional — it's good guidance regardless of whether the
    server runs with a private CA."""
    lines = [
        "Set up the {instance_brand} CLI on this machine.",
        "",
        "Server: {server_url}",
        "Personal access token: {token}",
        "(Just generated; treat it as a secret.)",
        "",
        "Run these, in order. The script is idempotent — safe to re-run if a step",
        "fails partway through. If a step fails with an unfamiliar error, paste the",
        "exact error back and stop. Do NOT improvise around TLS errors by disabling",
        "verification (`-k`, `NODE_TLS_REJECT_UNAUTHORIZED=0`,",
        "`git -c http.sslVerify=false`, etc.) — those are dead ends that hide the",
        "real problem.",
    ]
    if has_ca:
        lines.append(
            "The fallback chain inside step 0(d) is documented and OK to "
            "use; that's what fallback chains are for."
        )
    lines.append("")
    return lines


def _step_numbers(*, has_connectors: bool = True) -> dict[str, str]:
    """Compute the step numbers for the unified layout.

    Returns a dict keyed by logical step name; values are stringified
    1-based step numbers (preserving the existing string-based helper API
    so call sites stay diff-minimal).

    Steps (always emitted): install (1), mkdir/cd (2), init (3),
    catalog (4), preflight (5), marketplace (6), diagnose (7),
    connectors (8), restart_claude (9), confirm (10). Preflight +
    marketplace + connectors + restart_claude are always-on:
      - Marketplace registration is useful even when the operator has
        zero plugin grants (SessionStart hook reconciles future grants
        automatically).
      - Connectors (Asana / GWS / Atlassian) are per-connector default-yes
        asks — the user can decline each individually, so always-emitting
        the block costs nothing for users who skip everything. The
        Atlassian Remote MCP registration (`claude mcp add ...`) used to
        be its own step 6 but moved INTO the Atlassian connector's
        prompt body (atlassian_prompt() in app.web.connector_prompts) so
        everything Atlassian-related lives in one group — both the
        /home Atlassian tile and the inlined Atlassian sub-block in the
        setup script emit the same `claude mcp add` line as part of the
        standard connector setup.

    The interactive "Skills" step that previously sat between diagnose
    and Confirm was deleted in #242 — on-demand `agnes skills show
    <name>` is the one-size-fits-all default; bulk-copying every skill
    into ``~/.claude/skills/agnes/`` was an opinion question without an
    obvious right answer.

    `has_connectors` is kept as a parameter for future flexibility
    (default True). When set False, the connectors step is skipped and
    Confirm shifts down to step 7.

    Step-0 (TLS trust block) sits outside this numbering — it is gated by
    has_ca and has its own "0)" header rendered inside the trust block
    helper.
    """
    n = 5
    preflight = str(n); n += 1
    marketplace = str(n); n += 1
    diagnose = str(n); n += 1
    connectors = str(n) if has_connectors else ""
    if has_connectors:
        n += 1
    restart_claude = str(n); n += 1
    confirm = str(n)
    return {
        "preflight": preflight,
        "marketplace": marketplace,
        "diagnose": diagnose,
        "connectors": connectors,
        "restart_claude": restart_claude,
        "confirm": confirm,
    }


def resolve_lines(
    wheel_filename: str,
    *,
    plugin_install_names: list[str] | None = None,
    server_host: str = "",
    ca_pem: str | None = None,
    connector_prompts: dict[str, str] | None = None,
    instance_brand: str = "Agnes",
    workspace_dir: str = "Agnes",
) -> list[str]:
    """Return the template lines with server-side placeholders substituted.

    Pre-substitutes `{wheel_filename}` and `{server_host}`. Leaves
    `{server_url}` and `{token}` as placeholders for click-time JS
    substitution (or for `render_setup_instructions()` below).

    `ca_pem` (PEM-encoded fullchain of the Agnes server's TLS cert) gates
    the cross-platform step-0 trust-bootstrap block AND switches step 1 to
    the curl-then-local-install pattern AND switches step 5 to the
    platform-aware marketplace strategy. Caller decides whether the cert
    needs the bootstrap (typically: skip for publicly-trusted certs like
    Let's Encrypt, emit for self-signed or private corp CA).

    `connector_prompts` is a dict {slug: prompt_text} sourced from
    :func:`app.web.connector_prompts.all_connector_prompts`. When empty
    or None we fall back to the module's defaults (no operator GWS OAuth
    credentials baked in — the unconfigured GCP-walkthrough branch
    renders). Both the /home tiles and this setup script consume the
    same dict so the prompt text stays in lockstep across surfaces.

    Fallback: callers pass `"agnes.whl"` when no wheel is present on disk.
    The resulting URL (`/cli/wheel/agnes.whl`) will 404 at download time, but
    the instruction text still renders so operators can see the snippet shape
    and diagnose the missing wheel on the server.
    """
    names = list(plugin_install_names or [])
    has_ca = bool(ca_pem and ca_pem.strip())

    # Lazy default for connector_prompts. Imported inline so the
    # setup_instructions module stays import-light when callers don't
    # actually emit the connectors block (tests that hit a single helper
    # don't pay the cost of loading the prompt strings).
    if not connector_prompts:
        from app.web.connector_prompts import all_connector_prompts
        connector_prompts = all_connector_prompts()

    # Step layout. Preflight + marketplace + MCP go BEFORE diagnose;
    # connectors is the LAST interactive ask before Confirm — once plugins
    # + MCP + diagnose are settled, the only remaining work is plugging
    # the user's tools (Asana / GWS / Atlassian). The Skills step that
    # used to sit between diagnose and Confirm was deleted in #242
    # (on-demand `agnes skills show <name>` is the default;
    # bulk-copying skills was an opinion question).
    steps = _step_numbers(has_connectors=True)

    lines: list[str] = []
    if has_ca:
        lines.extend(_tls_trust_block(ca_pem))  # type: ignore[arg-type]
    lines.extend(_preamble_lines(has_ca=has_ca))
    lines.extend(_install_cli_lines(has_ca=has_ca))   # 1
    lines.extend(_init_lines())                        # 2, 3
    lines.extend(_preflight_block(steps["preflight"]))                       # 4
    lines.extend(_marketplace_block(names, step_num=steps["marketplace"]))    # 5
    # Standalone MCP step used to live here — moved INTO the Atlassian
    # connector's prompt body in step 7 so all Atlassian setup is grouped
    # together.
    lines.extend(_diagnose_lines(diagnose_num=steps["diagnose"]))             # 6
    # Connectors are the LAST interactive ask before the restart-claude
    # cue. Per-connector default-yes — empty/Enter is install, explicit
    # "no" skips.
    lines.extend(_connectors_block(
        steps["connectors"], connector_prompts,
        confirm_step_num=steps["confirm"],
    ))
    # Restart-claude lands between connectors and confirm so the user
    # picks up freshly-registered plugins / MCP servers / hooks on the
    # next session — without this every path silently expected the user
    # to know they had to re-launch.
    lines.extend(_restart_claude_lines(steps["restart_claude"]))
    lines.append("")
    lines.extend(_finale_lines(
        confirm_step_num=steps["confirm"],
        has_ca=has_ca,
    ))

    return [
        line
        .replace("{wheel_filename}", wheel_filename)
        .replace("{server_host}", server_host)
        .replace("{workspace_dir}", workspace_dir)
        .replace("{instance_brand}", instance_brand)
        for line in lines
    ]


def render_setup_instructions(
    server_url: str,
    token: str,
    wheel_filename: str = "agnes.whl",
    *,
    plugin_install_names: list[str] | None = None,
    server_host: str = "",
    ca_pem: str | None = None,
    connector_prompts: dict[str, str] | None = None,
    instance_brand: str = "Agnes",
    workspace_dir: str = "Agnes",
) -> str:
    """Render the setup instructions as a single string.

    Used server-side for tests and any non-JS rendering path. The browser
    clipboard flow uses the JS renderer embedded in the Jinja partial; both
    must produce byte-identical output for a given (server_url, token,
    wheel, plugins, host, ca_pem, connector_prompts, brand, workspace_dir) tuple.
    """
    lines = resolve_lines(
        wheel_filename,
        plugin_install_names=plugin_install_names,
        server_host=server_host,
        ca_pem=ca_pem,
        connector_prompts=connector_prompts,
        instance_brand=instance_brand,
        workspace_dir=workspace_dir,
    )
    text = "\n".join(lines)
    return text.replace("{server_url}", server_url).replace("{token}", token)