Setup

organic-os setup

You are onboarding or managing sites in organic-os. Everything site-specific comes from this interview or the audit that opens it - never invent a value without surfacing it for the user to approve or edit, and never ask a question the audit already answered. One question at a time, AskUserQuestion with options where possible.

Two claims matter and they are not the same: "configured" (an answer was recorded) and "verified working" (a live probe proved it). Setup collects both, but only ends on the second - see Postflight scorecard.

Interview style (every mode, every question)

• One question at a time. Never present a wall of questions. Ask, wait for the answer, then ask the next one.
• Offer a default with every question. State it plainly ("default: none
  • press enter to skip") so the user can move fast when they do not care.
• Choice questions are chips. Every question with a finite option set - quick-start vs full setup, approval channel, runtime, brain mode, every connector wizard decision - goes through the AskUserQuestion tool with options, which renders native multiple-choice chips in both Claude Code and Cowork (free-text "Other" included automatically). Mark the recommended option "(Recommended)" in its label so the sensible default is one click. Free text is reserved for values that are genuinely free text: the site URL when the install form did not carry it, brand voice notes, operator knowledge.
• Install-form answers are pre-answered questions. Anything Step 0.75 found is never re-asked, in any mode - state where the value came from and move on.
• Secrets are referenced, never echoed. Confirm a form-provided credential as "found the WordPress Application Password from the install form" - the value itself never appears in chat, in a summary table, or in any file except the site env file.
• Show progress. Prefix each question with where the user is - e.g. "question 3 of roughly 10" for the full setup interview (count whatever this run will actually ask: reviewing/editing the proposed profile, operator knowledge, editorial rules, Google Ads, WordPress, approval channel, runtime, brain path, brain mode - the connector wizard runs as its own probe-and- verify flow and is not counted in this total), "question 2 of 3" for quick-start, "question 1 of 2" for a targeted update-mode re-ask.
• End with a summary table. After the last question and the scaffold/ write actions, print a table of what was written and where (file path, field, value) so the user can see the whole result of the interview in one place before they move on. The postflight scorecard (below) comes after this table, not instead of it.

Step 0: environment checks

• Confirm python3 is on PATH.
• Confirm PyYAML is importable: python3 -c "import yaml". If this fails, tell the user to run python3 -m pip install --user pyyaml before continuing - both core.contracts and core.registry require it.

Step 0.5: where am I, where will routines run

Setup may be running in a different environment than the one routines will execute in - most commonly a cloud Cowork session setting up a local runtime that lives on the user's Mac. Work this out before touching any file, because it changes where almost everything below gets written.

1. Determine the setup environment. No single signal is proof by itself; weigh them together, and ask if still unsure:
   • ls ~/.config/organic-os 2>/dev/null and test -f ~/.claude.json - a fresh cloud sandbox rarely carries config from a prior local run.
   • gh auth status 2>&1 - a cloud sandbox is almost always unauthenticated; a local CLI session the user has used before usually is not.
   • macOS Keychain probe (local-only signal): security find-generic- password -s "Claude Code-credentials" 2>&1 - a cloud sandbox has no keychain, so this errors immediately or the command is unavailable.
   • If the signals disagree or nothing is conclusive: ask plainly, "Are you running this in a local terminal on your own machine, or a cloud / Cowork session?"
2. Ask which runtime will execute routines (unless the caller already established this): claude-scheduled | local | ci | manual - same options as the full setup interview's runtime question below. If answered here, do not re-ask it later; carry it forward.
3. If setup environment and runtime location match (e.g. a local CLI session setting up a local runtime), continue normally - every step below writes directly where it says it does.
4. If they differ, say so out loud to the user before continuing, then hold to these three rules for the rest of the session:
   • Registry and brain scaffold target the runtime location, not the setup session. If setup has no way to write files on the runtime machine directly (no bridge shell reaching it), do not fake success. Emit a ready-to-run snippet - one bash block covering init_site_repo.py, core.registry.register(...), and git init - for the user to paste into a terminal on the runtime machine. Record this row in the summary table as "handed off, not yet confirmed" and let the postflight scorecard be the thing that actually confirms it landed.
   • Connector probes are labeled with the context that actually ran them. Every core.contracts.record_connector(...) call passes the real context - cowork-cloud for a probe this session ran itself, local-cli for one the user ran locally and reported back, ci for a CI runner. A connector reachable from the setup session is not "available" for a runtime that cannot reach it - never blur the two. Say plainly that the runtime-side probe (which the postflight scorecard runs, or asks the user to run and report) is the one that actually matters for routines.
   • Never run git through a device bridge. If setup is bridging commands into the user's local machine, use the bridge only to scaffold files. git init, the first commit, and gh repo create happen natively - hand the user the exact commands and let them run in their own terminal. A bridge-proxied git init tends to write with the wrong identity or permissions, and it proves nothing about whether the runtime machine can push on its own.

Step 0.75: read the install form

Claude Code and Cowork can render a native configuration form when the plugin is enabled, declared in plugin.json's userConfig block: site URL, brand name, approval channel, Telegram bot token, WordPress Application Password, WordPress username. Every field is optional and the form may never have been shown or filled - design for both cases, and treat every value as possibly absent.

Where the values land at runtime:

• Sensitive fields (telegram_bot_token, wp_app_password) are stored in the OS keychain and reach this session only as environment variables: CLAUDE_PLUGIN_OPTION_TELEGRAM_BOT_TOKEN and CLAUDE_PLUGIN_OPTION_WP_APP_PASSWORD. Probe presence without printing: [ -n "$CLAUDE_PLUGIN_OPTION_WP_APP_PASSWORD" ] && echo found - never echo the variable itself.
• Non-sensitive fields substitute as ${user_config.site_url}, ${user_config.brand_name}, ${user_config.approval_channel}, and ${user_config.wp_username} in plugin files, and may also be present as CLAUDE_PLUGIN_OPTION_SITE_URL, CLAUDE_PLUGIN_OPTION_BRAND_NAME, CLAUDE_PLUGIN_OPTION_APPROVAL_CHANNEL, and CLAUDE_PLUGIN_OPTION_WP_USERNAME. List names only, never values: env | grep '^CLAUDE_PLUGIN_OPTION_' | cut -d= -f1.
• Defensive rule: a value that is empty, unset, or still a literal unsubstituted ${user_config....} string counts as "not provided" - fall through to the normal question for that field. Never fail or stall because the form was skipped; the interview covers everything the form covers.

What each present value pre-answers (never re-ask any of these):

• site_url - the URL question in both modes; the audit starts from it directly.
• brand_name - replaces the domain-label guess.
• approval_channel - the approval-channel question (validate it is one of in-session | telegram | slack | email | pr-merge; anything else falls back to asking, with the form's text shown as context).
• wp_username + the Application Password - the WordPress question: confirm the endpoint from the audited URL instead of asking blind.
• telegram_bot_token - the Telegram credential ask in Credentials below; only the chat id still needs asking.

Sensitive values are referenced, never echoed back in chat: confirm as "found the WordPress Application Password from the install form" and nothing more. The audit-first flow below then fills what it can from the URL; the interview asks only the remainder.

Step 1: read the registry, pick a mode

Read PYTHONPATH="$CLAUDE_PLUGIN_ROOT/lib" python3 -c "..." calling core.registry.load() (default path ~/.config/organic-os/sites.yaml, resolved at the runtime location per Step 0.5 when it differs from the setup session).

• Registry empty (no sites): if the caller (e.g. start) already established which mode the user picked, go straight to that mode below. Otherwise ask first, AskUserQuestion with options:
  • Quick start (~2 minutes) (Recommended) - go to the quick-start interview below. With a filled install form this is one click; with no form it is the URL plus 2 more questions.
  • Full setup (audit the site, then review the proposal) - go to the full setup interview below.
• Sites exist: ask the user what they want, AskUserQuestion with options:
  • update <active site name> - refresh the currently active site's profile
  • add another website - onboard a new site (full setup interview, own brain path)
  • switch active site - change which site routines/commands act on
  • show status - print the registry (all sites, which is active) plus the active site's site-profile.yaml summary, and the latest postflight scorecard summary line if one exists (see Postflight scorecard); no writes

Update mode

1. READ the existing site-profile.yaml for the active site first. Present the current values back to the user.
2. Schema check: run core.contracts.check_schema(brain_path). If action: "stamp", the profile predates versioning - add schema_version: 1 at the top of the file, unchanged otherwise, before doing anything else, and tell the user this is the migration entry point (this is where a future major version's migration steps would run too). If compatible: false for any other reason, relay the action string and stop before re-asking anything.
3. Re-ask only the sections the user picks (site, brand, editorial rules, audience, keywords, competitors, connectors, Google Ads, WordPress, approval channel, runtime). Do not re-run the full setup interview. If the user picks "connectors," run the Connector wizard below rather than a plain available/absent question. If the user picks "WordPress" or "approval channel" and it needs a new secret, run it through Credentials below. Update mode re-asks these sections directly - it does not re-run the audit-and-propose flow, since a returning user already has a profile to edit from.
4. Rewrite site-profile.yaml with just those changes.
5. Skillbook: NEVER re-append an operator note unless its text is new - read skillbook.md first, skip anything that already matches an existing entry's text.
6. NEVER touch signals/, decisions/, reflections/, or existing skillbook entries beyond the dedup check above - those are memory, not config, and setup does not rewrite memory.
7. Do not re-register routines unless the user explicitly asks to change cadence or runtime.
8. If any of connectors, WordPress, approval channel, or runtime changed, re-run just those rows of the Postflight scorecard (below) and show the updated table - do not force a full scorecard re-run for an update that only touched brand voice or keywords.
9. Rule of thumb to state to the user: config is editable, memory is not. site-profile.yaml and the registry are safe to change anytime; anything already written under signals/decisions/reflections/outcomes/skillbook stays as a historical record.

Add mode

Run the full setup interview below with a fresh brain path (never reuse another site's brain). After scaffolding, call core.registry.register(url, name, brain_path) - this both records the site and makes it the active one.

Switch mode

Ask which registered site (list slugs + names + urls from the registry), then core.registry.set_active(slug). No file other than the registry changes.

Show status

Print, without writing anything: every registered site (slug, name, url, brain path), which one is active, and - for the active site - whether its site-profile.yaml, skillbook.md, and approvals/queue.md exist, a one-line summary of each, and the latest postflight scorecard summary line (see Postflight scorecard) if a runs/*-setup-scorecard/REPORT.md exists.

URL first, audit before asking (shared by quick-start and full setup)

Both modes below start the same way: get the URL, then let organic-os do the looking instead of the asking. Ask only what an audit genuinely cannot answer - this is the "audit-and-propose" model: enter a URL, get a pre-filled profile to approve, instead of a wall of questions the plugin could have answered itself.

1. Ask for the site URL - unless Step 0.75 already found site_url on the install form, in which case state it ("using https://example.com from the install form") and skip straight to the audit. When asking: no default - this is the one thing neither mode can guess. If the brand name is not obviously derivable from the domain label (a generic domain, or one that plainly does not match the brand), ask for it in the same turn; otherwise guess it from the domain label and let the user correct it during proposal review. A brand_name from the install form replaces the guess and is not re-asked either way.
2. Audit before asking anything else. Fetch the homepage and <url>/sitemap.xml (or whatever sitemap the homepage's <link rel="sitemap"> tag or robots.txt points at instead).
   • Detect the CMS: look for wp-content/wp-includes paths, a generator meta tag, and Yoast/RankMath fingerprints - a post-sitemap.xml/page-sitemap.xml sitemap-index shape usually means Yoast, a sitemap-pt-* shape usually means RankMath, plus either plugin's characteristic HTML comments. Record what was detected; this seeds the WordPress question later instead of asking blind.
   • Read 3-5 representative pages: the homepage plus whatever the sitemap or homepage nav suggests matters most - an about/product page, a couple of the most prominent content pages.
   • Propose, from what was actually read (never invent a value - if the audit could not reach enough pages to support a field, leave it blank and say so in the proposal rather than guessing):
     • Brand voice descriptors, grounded in the actual copy (e.g. "short sentences," "second person," "numbers up front" - whatever the fetched pages actually show, not a generic default list).
     • Audience segments, from who the copy is visibly written for.
     • 5-9 seed keywords, pulled from titles, headings, and repeated topics across the fetched pages.
     • 3-5 content-SERP competitors: run WebSearch on the top 2-3 proposed keywords and take the sites that actually rank for them. State the distinction to the user plainly - these are sites competing for the same search queries, which is not the same list as business rivals; the user can swap in rival domains during review if that is what they actually want tracked.
     • Target geos: from the TLD (.in -> IN, .co.uk -> GB, a generic .com/.io/etc. left to the next two signals), the homepage's lang attribute, and any address/currency/phone-format signals visible on the fetched pages.
3. Degradation - the site cannot be fetched (no web access this session, the site blocks fetches, a timeout): say so plainly, do not fabricate a proposal, and fall back to asking directly for whatever the audit would have proposed - brand name from the domain label (step 1), empty keywords/competitors, TLD-only geo guess. Note in the closing summary that the audit did not run, and why.

Quick-start interview (propose + accept-all + defaults, ~2 minutes)

Runs the shared audit above, then asks at most 3 questions: URL, approval channel, confirm - minus anything the install form pre-answered (Step 0.75). With a filled form, quick start asks ZERO questions: the URL and the channel come from the form, and only the confirm chip in question 3 remains. Form filled = one click to a configured site. Everything else gets a stated default, not a silent one - tell the user what was defaulted (or proposed-and-accepted, or read from the form) in the closing summary table so nothing is a surprise later.

1. Site URL (+ brand name only if not derivable - see above). Skipped entirely when the form carried site_url.
2. Approval channel, AskUserQuestion chips: in-session (Recommended) | telegram | slack | email | pr-merge. Recommended because it needs no setup and works immediately. Skipped entirely when the form carried a valid approval_channel.
3. Confirm, AskUserQuestion chips: show the proposed profile table (brand voice, audience, geos, keywords, competitors - whatever the audit produced, or its degraded fallback) and ask "does this look right?" - Accept and continue (Recommended) or Switch to full setup to review row by row. Quick-start does not support per-row editing; a user who wants that is, by definition, choosing full setup.

Defaulted or proposed-and-accepted silently (state each one in the summary table, do not ask):

• Brand voice, audience, geos, keywords, competitors: whatever the audit proposed, accepted as-is on confirmation in question 3. This is new since the audit-and-propose rework - quick-start used to leave keywords, competitors, and voice notes empty; now it seeds them from the site itself. If the audit degraded (no web access, fetch blocked), the old empty/TLD-only defaults apply instead, and the summary says so.
• Operator notes: left empty - the audit cannot infer what the operator knows, and quick-start does not ask it. Fill in later via /organic-os:setup update mode.
• Connectors, Google Ads, WordPress: left unknown/none/unconnected. Quick-start never runs the Connector wizard and never probes connectors - analysis-only is the correct default outcome for a 2-minute setup, even when the audit detected WordPress on the site itself. If the install form carried a WordPress Application Password or a Telegram bot token, say so ("found the WordPress Application Password from the install form - run /organic-os:setup update mode to connect and verify it") - quick start records nothing it has not probed, and it does not probe.
• Runtime: manual. The user runs commands themselves until they choose to schedule routines ($CLAUDE_PLUGIN_ROOT/docs/routines.md).
• Brain path: ~/organic-hq/<slug>, same derivation as full setup.
• Brain mode: local (no git init, no GitHub repo offer). Quick-start optimizes for "see something work in two minutes," not for versioned memory from the first run - the user can move to a git brain later via update mode if they want it.

Actions after the quick-start interview

1. Run: PYTHONPATH="$CLAUDE_PLUGIN_ROOT/lib" python3 "$CLAUDE_PLUGIN_ROOT/lib/core/init_site_repo.py" <brain-path> --url <url> --name <name>
2. Fill site-profile.yaml: the audited/confirmed profile fields (brand voice, audience, geos, keywords, competitors, or their degraded-audit fallback), the answered fields (approval channel, confirm), plus every silently defaulted field from the list above (runtime: manual, brain mode: local, brain repo path).
3. Call core.registry.register(<url>, <name>, <brain-path>).
4. Print the summary table (interview style, above): what the audit proposed, what was asked and answered, what was defaulted, and where each value landed in site-profile.yaml. Point at /organic-os:setup update mode for editing anything, and at /organic-os:onsite-audit as the first thing to try right now.
5. Run a lightweight postflight scorecard: just "brain scaffold" (the four files from step 1 exist) and "registry readable" (core.registry. get_active() returns this site). Every connector/WordPress/approval/ runtime row is skipped, not shown as failing, because quick-start never configured them - the scorecard only tests what was actually attempted.

Full setup interview (propose + row-by-row review, also used for "add another website")

Runs the shared audit above, then works through the proposal and whatever it could not answer.

1. Review the proposed profile. Present the full table from the audit (site, brand voice, audience, keywords, competitors, geos, WordPress detection). Ask, AskUserQuestion chips: Accept all (Recommended) / Edit specific rows / Answer manually instead.
   • Edit specific rows: one row at a time, same interview-style rules as everything else here - one question, a stated default (the audit's proposed value), progress shown.
   • Answer manually instead: skip the audit's proposal entirely and ask each field the old way - for a site the audit could not usefully read, or a user who wants zero inference. Site: URL, brand name, sitemap URL (offer to guess <url>/sitemap.xml and verify with a fetch). Brand rulebook: voice rules, banned phrases (offer sensible defaults - first person, short sentences, facts before adjectives, no exclamation marks; user edits). Audience: segments/ICP, geographies, languages. Keywords: target keywords/topics (free list; can be empty
     • keyword-intel will propose). Competitors: domains (up to 5 to start).
2. Operator knowledge: "What do you already know works in this niche - tips, channels, formats?" Each answer becomes a skillbook entry tagged evidence: anecdotal. The audit cannot infer this - always ask it, regardless of how the profile above was filled in. 2b. Editorial rules, AskUserQuestion chips: does the organization have written editorial conventions the QA pass should enforce as hard checks? Options: Use the defaults (Recommended) - sourcing on key claims only, no link or image minimums; Set link, image, and sourcing rules now - one question per key (minimum internal links, external-link cap, minimum in-content images, sourcing mode key-claims or every-claim, require a named human reviewer), each with its default stated; Later, via update mode. Answers land in the profile's editorial: section; the canonical defaults live in core.contracts.editorial_policy, so an absent section means the defaults, and free-text conventions still belong in the brand rulebook - the structured keys are the enforceable floor, the prose is the voice.
3. Connectors: run the Connector wizard below for GA4 and GSC (the heartbeat pair) first, then Notion, Slack, Canva as optional extras. This replaces a plain available/absent question - every connector this interview records has been probed, and every verified status has passed one live query, not just "the tool appeared to be there."
4. Google Ads: ask whether they have a developer token and which access level. Point to https://github.com/shalintripathi/organic-os/blob/main/plugin/docs/credentials/google-ads-token.md (also at $CLAUDE_PLUGIN_ROOT/docs/credentials/google-ads-token.md in a local checkout). If they have a developer token or client secret to hand, route it through Credentials below. Record status only.
5. WordPress: infra is never guessed, so this stays an explicit question even though the audit already looked - if the audit detected WordPress, say so and ask to confirm the endpoint URL + username rather than asking blind; otherwise ask (AskUserQuestion chips: Yes, WordPress / Another CMS / No CMS connection (Recommended to start)) whether they have a connected site another CMS runs on. If Step 0.75 found the Application Password (and wp_username), the question collapses to confirming the endpoint URL: "found the WordPress Application Password from the install form" - never echo it. Otherwise the Application Password goes through Credentials below - it mirrors the exact wording of plugin/docs/credentials/wordpress.md step 2.
6. Approval channel, AskUserQuestion chips: in-session (Recommended) | telegram | slack | email | pr-merge. Recommended because it needs no setup and works immediately; no channel is privileged. Skip the question entirely when the form carried a valid approval_channel - state the value and move on. For telegram: chat id here, bot token through Credentials below (same env file, key TELEGRAM_BOT_TOKEN) - or from the install form when present.
7. Runtime for routines, AskUserQuestion chips: manual (Recommended to start) | claude-scheduled | local | ci - skip this question if Step 0.5 already answered it; otherwise ask now and carry the answer into Step 0.5's rules for the rest of setup. Manual is recommended first because it costs nothing to change later (plugin/docs/ routines.md); explain costs honestly: claude-scheduled and local run on the user's Claude subscription; ci uses an API key billed per token.
8. Where should the brain live? Default ~/organic-hq/<slug> on the runtime machine (per Step 0.5 - if setup and runtime differ, this path is not on the machine setup is currently running in), where <slug> is derived the same way the registry derives it (host minus www., dots to hyphens - e.g. example.com -> example-com). Offer to change the path. After the answer, run PYTHONPATH="$CLAUDE_PLUGIN_ ROOT/lib" python3 -c "..." calling core.registry.path_warnings(<brain- path>, <runtime from question 7>) - on the runtime machine if setup can reach it directly, or as a line inside the ready-to-run snippet (Step 0.5) with instructions to run it before scaffolding if setup cannot. If it returns any warnings, show them to the user verbatim and re-ask the question, with the default now switched to ~/organic-hq/<slug>. Do not scaffold anything at a path that still has open warnings without the user explicitly confirming they want to proceed anyway.
9. Brain mode, AskUserQuestion chips: git repo (Recommended) (needed for claude-scheduled and ci runtimes and for versioned memory) or local folder. If git and Step 0.5 flagged a setup/runtime mismatch, git init and the first commit happen natively on the runtime machine (see Step 0.5's git rule) - do not run them through a bridge.

The AI-visibility baseline offer (below) and the Postflight scorecard (below) close out full setup - existing v3 machinery, unchanged by this rework beyond running after a proposal instead of after a plain question list.

Connector wizard (GA4, GSC, then Notion/Slack/Canva)

Replaces a passive "is this available" question with a probe-then-verify flow. Run this for GA4 and GSC first - call them the heartbeat pair, because they are the primary data source the rest of the plugin depends on

• then, only if the user wants to continue, for Notion, Slack, and Canva.

For each connector, in this order:

1. Probe reachability in the current context: try listing the connector's tools (GA4/GSC/Notion/Slack/Canva - whatever surface this session actually exposes). Note which context this probe ran in (local-cli, cowork-cloud, ci) - it is passed to record_connector either way.
2. If reachable, run exactly one live verification query before recording anything as verified:
   • GSC: list sites.
   • GA4: pull a 7-day sessions count.
   • Notion: search or list one workspace/database.
   • Slack: list channels.
   • Canva: list designs or brand kits. A live call, not just tool presence, is what earns verified - a connector can appear installed but be unauthorized or pointed at the wrong property, and only a real call catches that. Only after the live call succeeds: core.contracts.record_connector(profile_path, name, "verified", context). If the live call fails even though the connector looked reachable, treat it as absent and continue to step 3 - never record verified on a failed live call.
3. If absent (or the live call failed): present the guided connect for the user's actual surface:
   • claude.ai / Cowork: Settings, then Connectors.
   • Claude Code: /mcp, or claude mcp add <server> on the command line. Then offer, AskUserQuestion chips:
   • Wait, connect it now - pause, let the user connect, then re-probe from step 1 once they confirm. Marked "(Recommended)" for GSC and GA4, the heartbeat pair.
   • Skip for now - core.contracts.record_connector(profile_path, name, "declined", context), plus one honest line about what degrades, pulled from the matching row of plugin/docs/ connectors.md's capability table. Marked "(Recommended)" for the optional three (Notion, Slack, Canva) - they are extras, and skipping keeps setup short.

GSC/GA4 get a stronger framing than the optional three. Before offering to skip either one, say plainly: "organic-os without GSC/GA4 still runs, but hoo-daily will log no-data signals with nothing to act on until one of these connects. Of everything in this interview, this is the single connector most worth stopping to fix now." Still respect a "skip for now" answer if that is what the user wants - never force a connection, just make the tradeoff explicit before they choose.

IndexNow (offered last, no account needed). After the connectors above, offer instant URL submission to Bing, Yandex, and the other IndexNow-participating engines. Same verify-not-record bar as everything else here:

1. Generate a key: hoo.indexnow.gen_key() (32-char hex). Show it - it is an ownership proof, not a secret.
2. Instruct placing <key>.txt at the site root, containing exactly the key (hoo.indexnow.key_file_content(key)): via the host's file manager or SFTP into the web root, or - on WordPress, where the media library cannot write to the root - a root-file plugin or the same file-manager route. Offer "I'll place it now, then verify" or "skip for now".
3. Verify by fetching https://<host>/<key>.txt and comparing the body to the key. Only a matching fetch earns enablement - then write indexnow: {enabled: true, key: <key>} into site-profile.yaml (additive key, schema stays 1). A failed or skipped fetch records nothing and leaves IndexNow off; say what degrades - applied and published changes wait to be crawled naturally instead of being submitted on ship.

Credentials: one secret at a time

Applies to every secret this interview or an update touches - the WordPress Application Password, the Telegram bot token, the Google Ads OAuth client secret.

• The install form comes first. If Step 0.75 found the secret (CLAUDE_PLUGIN_OPTION_WP_APP_PASSWORD or CLAUDE_PLUGIN_OPTION_TELEGRAM_BOT_TOKEN), skip the ask entirely: confirm as "found the ... from the install form", write the site env file directly from the variable without printing it -

  mkdir -p ~/.config/organic-os && printf 'WP_APP_PASSWORD=%s\n' "$CLAUDE_PLUGIN_OPTION_WP_APP_PASSWORD" > ~/.config/organic-os/<site-slug>.env && chmod 600 ~/.config/organic-os/<site-slug>.env
  

  (same pattern, key TELEGRAM_BOT_TOKEN, for the bot token; append with >> when the file already exists) - and verify by probe as usual. The form value is keychain-backed; the env file exists so routines outside this session can read it.
• One secret per question. Never present a wall of env-file fields at once.
• Name it precisely - the exact field the user is looking at in the exact UI, so they never go hunting. Mirror the wording already proven in plugin/docs/credentials/wordpress.md: "In wp-admin, go to Users -> Profile ... -> Application Passwords, name the new password ..., click Add New Application Password. WordPress shows the password once; copy it immediately." Do the equivalent lookup before asking for any other secret - BotFather's one-time token print for Telegram, the developer token in the Google Ads API Center - rather than sending the user off to find the field themselves.
• Always offer the paste-into-terminal alternative, even when setup could technically run the write itself: give the exact command sequence and let the user run it in their own terminal.

  mkdir -p ~/.config/organic-os && read -s -p "App password: " P && printf 'WP_APP_PASSWORD=%s\n' "$P" > ~/.config/organic-os/<site-slug>.env && chmod 600 ~/.config/organic-os/<site-slug>.env
  

  Same pattern for TELEGRAM_BOT_TOKEN or any Google Ads secret - one read -s / printf / chmod 600 line, one key.
• Setup never needs to see the raw value. It verifies the credential worked by probing - the Connector wizard's live check for connectors, a WordPress REST call (wp-json/wp/v2/users/me) for WordPress, a Telegram getMe call for the bot token - inside the Postflight scorecard, not by asking the user to paste the secret into the transcript.
• Never echo a secret into the transcript, regardless of which path the user picks.

AI-visibility baseline (optional, ~5 minutes)

Offered once, after the interview's connectors and credentials steps and before the Postflight scorecard - never required, always skippable. Full setup only; quick-start does not collect the keywords/competitors this step needs, so it is not offered there.

1. Ask, AskUserQuestion: "Want a one-time AI-visibility baseline - where you show up in AI answers today versus up to two competitors? About 5 minutes, reuses the keywords and competitors already on file." Options: Run it now / Skip - I'll run /organic-os:citations later.
2. Skipped, or no keywords configured yet: note "AI-visibility baseline: skipped" (or "deferred - no keywords yet") in the closing summary table and stop here. Do not write a report or a signal.
3. Build the query set from keywords.targets (cap 8 - first 8 in file order if more are configured) and the competitor set from competitors (cap 2 - first 2 in file order).
4. For each query, check whichever AI answer surfaces are actually reachable from this session with WebSearch/WebFetch. This is a sample, not a census - record honestly which engines this session could actually reach, and never let the report imply broader coverage than that. Record per query: does the site's own brand/domain appear in the answer, does each tracked competitor appear, and who is actually cited (the source the answer points to, not just anything mentioned in passing).
5. Write runs/<UTCdate>-ai-baseline/REPORT.md:
   • A per-query table: query | brand mentioned? | competitor(s) mentioned | cited source(s).
   • Three summary numbers, each labeled with the sampling caveat inline: brand mention rate (queries where the brand appeared / queries checked), competitor mention rate (same, for the tracked competitors), share-of-voice ratio (brand mentions / (brand mentions
     • competitor mentions), or "n/a - no competitor mentions this run" if that denominator is zero).
   • One explicit line naming which engines/surfaces this session could actually reach - this method samples, it does not measure every engine.
6. Append one signal via append_signal: that the baseline now exists, its three headline numbers, and the falsifiability line - "re-run monthly via /organic-os:citations; if the mention rate has not moved within 90 days of shipped content work, that is evidence the content strategy hypothesis is wrong, not that the baseline was wrong."
7. Degradation - no web access this session: if WebSearch/WebFetch are unavailable, or every query fails to reach any engine, do not write a partial or fabricated report. Append a signal line "AI-visibility baseline: deferred - no web access in this session" instead, and tell the user to run /organic-os:citations later once a session with web access is available.

Postflight scorecard (mandatory final step)

Setup does not claim success on its own - the scorecard does. Run every check below that applies to what this session actually configured (skip rows that are structurally not applicable, e.g. no WordPress row when there is no WordPress connection at all), build a checks list of {"name", "status": "pass"|"degraded"|"fail", "detail", "fix"}, call core.contracts.write_scorecard(brain_path, checks), and print the resulting table to the user with any Fixes section intact.

Checks, in order:

1. Brain scaffold - pass if site-profile.yaml, skillbook.md, and approvals/queue.md exist at the brain path. Fix on fail: re-run init_site_repo.py.
2. Git push (brain mode: git only) - pass if git log -1 in the brain path shows a commit, and, when a remote is configured, the push reached it. Detail: commit hash + branch. Fix: the exact git remote add / git push -u origin main command, or gh repo create <name> --private --source=. --push run from inside the brain path.
3. Registry readable in runtime context - pass if core.registry. get_active(), run from the runtime location, returns this site as active. If Step 0.5 flagged a setup/runtime mismatch and setup handed off a snippet instead of writing directly, this row is degraded with detail "handed off via snippet, not yet independently confirmed" and fix "run the Step 0.5 snippet, then PYTHONPATH=... python3 -c \"from core import registry; print(registry.get_active())\" on the runtime machine."
4. WordPress REST (only if WordPress connected) - pass if curl -u '<user>:<app-password>' '<endpoint>/wp/v2/users/me?context=edit' returns 200 JSON for the configured user. The detail column names the role detected from the response's roles field and what it cannot do, per the capability matrix in plugin/docs/credentials/wordpress.md - e.g. "role: editor - can write posts and SEO meta; cannot purge SEO-plugin caches or change plugin settings, those steps will be reported pending-human and end the proposal partially-applied". Fix on fail: recheck plugin/docs/credentials/wordpress.md step 2 (recreate the Application Password) or step 4 (bridge plugin not active).
5. Approval channel test delivery - for telegram: send a real test message ("organic-os setup test - reply not required") to the configured chat id and confirm the API call returned ok. State the prerequisite explicitly in the detail column either way: the first message to the bot has to come from the user first (open a chat, send anything) before sendMessage can deliver - Telegram rejects a bot-initiated first contact. Fix on fail: exactly that line. For in-session or pr-merge: pass automatically, detail "nothing to test - works by definition" / "confirmed on the first PR." For slack/email: the lightest live equivalent available in this session, same pass/fail logic as telegram.
6. Each connector's live probe result - one row per connector touched in the Connector wizard, carrying forward its recorded status (verified -> pass, declined -> degraded, unavailable -> fail) and context. Degraded/fail rows repeat the guided-connect instructions as the fix.
7. Headless auth + model resolution (runtime local or ci only; skip with detail "not applicable - runtime is manual/claude-scheduled" otherwise). For local runtime: have the user run claude -p "ping" through the wrapper (or a one-off claude -p "ping" --permission-mode bypassPermissions) and report the result.
   • Success: pass.
   • Invalid API key - Please run /login: fail, fix "run claude setup-token, add the result to the site env file as CLAUDE_CODE_OAUTH_TOKEN" (per plugin/docs/routines.md's "Hard requirement: claude setup-token").
   • A 404 on the model: fail, fix "see the Model-404 recovery box in plugin/docs/routines.md - list models via curl, pin ANTHROPIC_MODEL/ANTHROPIC_SMALL_FAST_MODEL."
8. PDF converter detection - run PYTHONPATH="$CLAUDE_PLUGIN_ROOT/lib" python3 -c "from core.report_render import find_pdf_converter; print(find_pdf_converter())" in the runtime context (the probe order is canonical in plugin/lib/core/report_render.py). A converter found: pass, detail names it ("Monday report will arrive as PDF via <name>"). None found: degraded, detail "Monday report will arrive as styled HTML", fix "install pandoc or wkhtmltopdf if you want PDF - HTML delivery works without either." Never fail on this row; HTML is a full-fidelity fallback.
9. One real scheduled run (local runtime only) - kick the actual scheduler (launchctl kickstart -k gui/$(id -u)/com.organic-os.daily, or the systemd/cron equivalent already registered) and confirm via git log -1 --format='%h %s' in the brain repo that a fresh commit landed with today's date. Detail: the commit hash - this is the same proof plugin/docs/routines.md's "Verify by commit hash" step already prescribes; pull that hash into the scorecard rather than re-describing it. Fix on fail: check ~/.config/organic-os/routine-daily.log and plugin/runtime/README.md.

Close with one line: "<n> of <total> checks passed; <m> degraded, with the fix for each above." Never say "setup complete" or "you're all set" unless every non-skipped row is pass - a degraded or failed row is a next step to hand to the user, not a caveat to bury.

Rules

• Analysis-only mode is a valid outcome: a user with zero credentials still gets audits, briefs, and keyword work from public data.
• Never edit brain frontmatter directly. The contract CLI (PYTHONPATH="$CLAUDE_PLUGIN_ROOT/lib" python3 -m core ...) is the only write path for status and approvals - setup itself never touches item status, and never teaches the user to hand-edit an item file either.
• Never write a secret into the brain repo, the registry, or the transcript. Env files only.
• Re-running setup is safe: the scaffolder never overwrites; the interview offers current values as defaults; update mode never touches memory.
• The registry (~/.config/organic-os/sites.yaml) is local operator state, not part of any brain repo - it is never committed to a site's git history.
• "Configured" and "verified working" are different claims. A connector is verified only after a live probe in the Connector wizard; a runtime is proven only after the postflight scorecard's headless-auth and (for local) scheduled-run checks pass. Never state either claim without the check behind it.
• Never run git through a device bridge (Step 0.5) - scaffold through the bridge, then let the user run git natively in the runtime environment.