From 1af13e41402a22a4ecd8c12fe94272ca2dff7497 Mon Sep 17 00:00:00 2001 From: Jing Xie Date: Wed, 20 May 2026 09:14:28 -0400 Subject: [PATCH] Sync clarion-setup: leaner install + free-tier reasoning default MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two changes carried from jingerzz/clarion-intelligence-system: 1. **SKILL.md — persona/rule install removed from autonomous path.** The upstream `clarion-setup` no longer installs the 7 Clarion personas + 8 routing rules during its autonomous install. Those moved to an opt-in follow-up prompt (*"install Clarion personas and routing rules"*) because the persona/rule parsing of the 62KB PERSONAS-AND-RULES.md doc was consuming ~5 minutes of the install path (vs ~30 seconds for the rest). Skills are functional standalone — the persona layer is chat-UX discipline, not a functional gate. Updated frontmatter description, Flow at a glance, idempotency, and on-error sections accordingly. Step count drops from 9 to 7. 2. **setup.py — sync free-tier reasoning_model default (PR #23).** Back-syncs PR #23 in the upstream repo: the `DEFAULT_CONFIG[ "reasoning_model"]` shipped by the bootstrap setup.py was still subscriber-tier `zo:anthropic/claude-opus-4-7` in the registry, while the upstream repo updated to free-tier `zo:openai/gpt-5.4-mini` weeks ago. The mismatch meant fresh installs from the registry got a subscriber-tier default despite ARCHITECTURE.md's "all defaults are free-tier" policy. Both are now aligned. Upstream PR: jingerzz/clarion-intelligence-system#27 Validator: `bun validate` passes (warnings exist for other skills, not clarion-*). Co-Authored-By: Claude Opus 4.7 --- External/clarion-setup/SKILL.md | 96 +++++++------------------ External/clarion-setup/scripts/setup.py | 6 +- 2 files changed, 30 insertions(+), 72 deletions(-) diff --git a/External/clarion-setup/SKILL.md b/External/clarion-setup/SKILL.md index 18903e3..bb10dad 100644 --- a/External/clarion-setup/SKILL.md +++ b/External/clarion-setup/SKILL.md @@ -1,6 +1,6 @@ --- name: clarion-setup -description: Bootstraps the Clarion Intelligence System on Zo Computer. Run this once after installing — clones the source repo, installs the ai_buffett_zo Python library, creates the workspace data tree under /home/workspace/clarion/ (auto-detected on Zo), auto-installs all nine sibling clarion-* skills (regime-check, sec-research, single-stock-eval, expected-return-calc, value-screener, thesis-write, thesis-monitor, watchlist-update, living-letter-update) under /home/workspace/Skills/, registers the sec-indexer background service, and installs the 7 Clarion personas + 8 routing rules into Zo Settings. Idempotent (safe to re-run; asks before replacing customized personas/rules). The only manual step is one batched human checkpoint near the end (SEC EDGAR name + email, and creating the ZO_API_KEY secret). Use when the user asks to "set up Clarion" or "install Clarion". +description: Bootstraps the Clarion Intelligence System on Zo Computer. Run this once after installing — clones the source repo, installs the ai_buffett_zo Python library, creates the workspace data tree under /home/workspace/clarion/ (auto-detected on Zo), auto-installs all nine sibling clarion-* skills (regime-check, sec-research, single-stock-eval, expected-return-calc, value-screener, thesis-write, thesis-monitor, watchlist-update, living-letter-update) under /home/workspace/Skills/, and registers the sec-indexer background service. Idempotent (safe to re-run). The only manual step is one batched human checkpoint near the end (SEC EDGAR name + email, and creating the ZO_API_KEY secret). Persona routing for Clarion is opt-in via a separate prompt after install ("install Clarion personas and routing rules"). Use when the user asks to "set up Clarion" or "install Clarion". metadata: author: cis.zo.computer category: External @@ -14,7 +14,9 @@ Bootstraps the Clarion Intelligence System on a Zo workspace. Run this once befo ## Flow at a glance -This skill is designed for a **single-prompt install** experience. Steps 1–5 run autonomously (clone, library, data tree, register service, install personas + rules). Step 6 is one batched human checkpoint — the user supplies their SEC EDGAR identification and creates the `ZO_API_KEY` secret in Zo Settings. Steps 7–9 resume autonomously to apply the user's input, restart the service, verify it's running, and report. +This skill is designed for a **single-prompt install** experience that delivers the working system (library, skills, service) fast — typically ~30 seconds of autonomous work plus the user's time creating the `ZO_API_KEY` secret. Steps 1–3 run autonomously (clone, library, data tree, register service). Step 4 is one batched human checkpoint — the user supplies their SEC EDGAR identification and creates the `ZO_API_KEY` secret in Zo Settings. Steps 5–7 resume autonomously to apply the user's input, restart the service, verify it's running, and report. + +**Personas and routing rules are NOT installed by this skill.** They're the chat-layer discipline (regime-first framing, kill-condition enforcement, persona handoff between Macro Sentinel → Analyst → Thesis Architect → Portfolio Manager). The bare install delivers everything needed to evaluate a stock from chat; persona routing is opt-in via a follow-up prompt described in Step 7 — typically a separate ~3-minute step the user takes after they've tried a few queries. Walk through the steps below in order. Stop and surface any failure to the user immediately — do not proceed past a failure. @@ -48,7 +50,7 @@ The script is idempotent. It will: - Verify the `sec-indexer` console script is on PATH - Install every sibling `clarion-*` skill from the repo into `/home/workspace/Skills/` (refreshes any already-installed copies; pass `--skip-skills` to opt out) - Print service registration parameters between `--- BEGIN SERVICE_REGISTRATION ---` and `--- END SERVICE_REGISTRATION ---` -- Print a `USER_ACTION_REQUIRED` block (you'll surface this in Step 6) +- Print a `USER_ACTION_REQUIRED` block (you'll surface this in Step 4) - Print a final `SETUP_RESULT: ok` line on success, or `SETUP_RESULT: error: ` on failure If you do NOT see `SETUP_RESULT: ok`, surface the error to the user verbatim and stop. @@ -70,67 +72,20 @@ Use the `register_user_service` agent tool with the parameters printed in the `S {"ZO_API_KEY": "$ZO_API_KEY", "CLARION_DATA_ROOT": "/home/workspace/clarion"} ``` -Do **not** wrap it in quotes and escape it like `"{\"ZO_API_KEY\": \"$ZO_API_KEY\", ...}"`. If the tool call appears to require escape sequences inside `env_vars`, stop and re-form the call — the parameter is an object, not a string. Models that try to escape this end up generating malformed input that either fails outright or — worse — succeeds with corrupted values (env vars inlined into the entrypoint shell-string, trailing XML-tag artifacts appended to the entrypoint, `CLARION_DATA_ROOT` silently dropped). The verification at Step 8 catches the corrupted-success case; the prevention is to get the env_vars shape right here. +Do **not** wrap it in quotes and escape it like `"{\"ZO_API_KEY\": \"$ZO_API_KEY\", ...}"`. If the tool call appears to require escape sequences inside `env_vars`, stop and re-form the call — the parameter is an object, not a string. Models that try to escape this end up generating malformed input that either fails outright or — worse — succeeds with corrupted values (env vars inlined into the entrypoint shell-string, trailing XML-tag artifacts appended to the entrypoint, `CLARION_DATA_ROOT` silently dropped). The verification at Step 6 catches the corrupted-success case; the prevention is to get the env_vars shape right here. -**Expected state after Step 3: the service is in `FATAL` or `BACKOFF`.** This is normal and expected. `$ZO_API_KEY` resolves from a Zo secret that doesn't exist yet (the user creates it in Step 6). The supervisor will try to launch `sec-indexer`, the binary will fail to authenticate against Zo's API, and the service will retry-backoff. **Do NOT call `service_doctor` yet. Do NOT delete and re-register. Continue to Step 4.** The restart in Step 7, after the secret exists, brings the service to RUNNING. +**Expected state after Step 3: the service is in `FATAL` or `BACKOFF`.** This is normal and expected. `$ZO_API_KEY` resolves from a Zo secret that doesn't exist yet (the user creates it in Step 4). The supervisor will try to launch `sec-indexer`, the binary will fail to authenticate against Zo's API, and the service will retry-backoff. **Do NOT call `service_doctor` yet. Do NOT delete and re-register. Continue to Step 4.** The restart in Step 5, after the secret exists, brings the service to RUNNING. If `register_user_service` itself returns an error (not just a FATAL state — an actual tool error), check the env_vars formatting above first, then surface the error. -## Step 4 — Install the 7 Clarion personas - -Read `/home/workspace/clarion-intelligence-system/docs/PERSONAS-AND-RULES.md`. - -For each of the 7 personas — sections `## Persona 1 — Data-First Plain Talk` through `## Persona 7 — Clarion LP Voice`: - -1. **Extract the persona name** from the section heading. Examples: - - `## Persona 1 — Data-First Plain Talk` → name is `Data-First Plain Talk` - - `## Persona 2 — Clarion Macro Sentinel` → name is `Clarion Macro Sentinel` -2. **Extract the persona's prompt text** — it's the contents of the *outermost* triple-backtick code block within the persona's section (before the next `## Persona` heading or the next top-level section). Note: persona prompts contain *nested* triple-backtick blocks for bash examples; you want the outermost one only. -3. **Check whether a persona with this name already exists**: - - Call `list_personas()` and filter client-side by `name`. - - If a match exists, ask the user: *"I see an existing Clarion persona named '\'. Replace it with the latest version from the doc? (yes/no)"* Wait for the answer. - - If **yes**: call `delete_persona(persona_id=)`, then proceed to create. - - If **no**: skip this persona entirely; do not create a duplicate. Note the existing `id` in the persona-ID map for Step 5. - - If no match exists, proceed to create. -4. **Create the persona**: call `create_persona(name="", prompt="")`. The tool response contains the new persona's `id`. If the response shape is unexpected and you can't find the `id`, fall back to calling `list_personas()` again and filtering by name to recover the new id. -5. **Record** the mapping `{persona_name → persona_id}` for use in Step 5. - -After all 7 personas, you should have a complete mapping covering all 7 Clarion persona names. Surface any persona that was skipped (user said "no" to replacement) — the corresponding rule in Step 5 still needs an ID to reference, so the existing persona's ID must be in the map. - -## Step 5 — Install Clarion rules - -Read the same `PERSONAS-AND-RULES.md` file. **Install Rules 3, 5, 6, 7, 8, 9, 10, and 11. SKIP Rules 1, 2, and 4** — they reference operator-personal infrastructure not installed by Clarion (memory layer, Zo Space verification). The doc has explicit scope notes confirming this. - -For each rule to install: - -1. **Extract the rule's Condition text** — the prose body after `**Condition:**` (a single paragraph, not in a code block). -2. **Extract the rule's Instruction text** — the contents of the triple-backtick block under `**Instruction:**`. -3. **For Rules 5–11 (the routing rules)**, the Instruction text contains a persona ID. The doc's checked-in value is the author's instance-specific UUID OR the placeholder `` (for Rule 11). **Replace it with the actual persona ID** you captured in Step 4, matched by name: - - Rule 5 (stock evaluation) → `Clarion Analyst` - - Rule 6 (regime questions) → `Clarion Macro Sentinel` - - Rule 7 (thesis monitoring / portfolio status) → `Clarion Portfolio Manager` - - Rule 8 (thesis writing) → `Clarion Thesis Architect` - - Rule 9 (value screens) → `Clarion Value Screener` - - Rule 10 (investor letter) → `Clarion LP Voice` - - Rule 11 (return to default) → `Data-First Plain Talk` -4. **Check whether a Clarion routing rule with this condition already exists**: - - Call `list_rules()` and compare each existing rule's condition text to the one you're about to install. Compare the first ~80 characters (handles minor wording variations across doc versions). - - If a match exists, ask the user: *"I see an existing Clarion rule for '\'. Replace it? (yes/no)"* Wait for the answer. - - If **yes**: call `delete_rule(rule_id=)`, then proceed to create. - - If **no**: skip this rule. - - If no match exists, proceed to create. -5. **Create the rule**: call `create_rule(instruction="", condition="")`. - -Total expected after Step 5: **8 Clarion rules installed** (Rule 3 + Rules 5–11). - -## Step 6 — Batched human checkpoint (the only manual step) +## Step 4 — Batched human checkpoint (the only manual step) **Pre-check (skip the whole checkpoint on a clean re-run).** Before asking the user for anything, check both of: 1. `/home/workspace/clarion/config.json`'s `sec_user_agent` field — is it the placeholder `Clarion Intelligence System (clarion@example.com)`, or a real user value? 2. `service_doctor(service="sec-indexer")` — is the service already RUNNING with non-zero uptime? (If yes, the `ZO_API_KEY` secret already exists, since the service couldn't have started without it.) -If `sec_user_agent` is a real value AND the service is already RUNNING, **skip Step 6 entirely** — there's nothing for the user to do. Tell the user *"detected a complete prior install — skipping the human checkpoint and going straight to a refresh restart."* Jump to Step 7b (restart only, no config.json write needed). +If `sec_user_agent` is a real value AND the service is already RUNNING, **skip Step 4 entirely** — there's nothing for the user to do. Tell the user *"detected a complete prior install — skipping the human checkpoint and going straight to a refresh restart."* Jump to Step 5b (restart only, no config.json write needed). Otherwise, you need at least one of two inputs from the user. **Surface both together so they can multitask** — the user can type their SEC identification in chat while simultaneously navigating Zo Settings to create the secret. @@ -154,9 +109,9 @@ Wait for the user to reply with: If the user only replies to one of the two, prompt for the other before continuing. -## Step 7 — Apply user inputs and restart the service +## Step 5 — Apply user inputs and restart the service -### 7a — Write the SEC user-agent to config.json (only if Input A produced a value) +### 5a — Write the SEC user-agent to config.json (only if Input A produced a value) Substitute the user's reply into this command and run it: @@ -166,7 +121,7 @@ python3 -c "import json, pathlib; p = pathlib.Path('/home/workspace/clarion/conf Replace `` with the user's exact reply (no quotes around it inside the Python string — the outer quotes are already there). Confirm the write by reading the file back and showing the `sec_user_agent` line. -### 7b — Restart the sec-indexer service +### 5b — Restart the sec-indexer service Call `update_user_service` with the existing `sec-indexer` service_id and `action="restart"`. This: - Causes the supervisor to re-evaluate `$ZO_API_KEY` (now that the secret exists) @@ -174,7 +129,7 @@ Call `update_user_service` with the existing `sec-indexer` service_id and `actio Confirm the restart command succeeded. -## Step 8 — Verify the service is actually running (do not skip) +## Step 6 — Verify the service is actually running (do not skip) Call the `service_doctor` agent tool: @@ -202,11 +157,12 @@ As a separate (weaker) sanity check that the binary is reachable on PATH: ```bash sec-indexer --help + ``` -This proves the executable resolves on PATH, but does NOT prove the service is running. Step 8's `service_doctor` is the actual validation. +This proves the executable resolves on PATH, but does NOT prove the service is running. Step 6's `service_doctor` is the actual validation. -## Step 9 — Report and explain +## Step 7 — Report and explain Tell the user: @@ -216,13 +172,13 @@ Tell the user: > - Workspace data: the path printed in the `[2/6] Creating data tree under …` line from setup.py (typically `/home/workspace/clarion/` on Zo, `~/clarion/` on a local machine — auto-detected) > - Background service: `sec-indexer` (running) > - Skills installed under `/home/workspace/Skills/`: every sibling `clarion-*` skill from setup.py's `[5/6]` block. List the actual names returned. -> - Personas installed in Zo Settings → AI: the 7 Clarion personas you created in Step 4. List them by name (Data-First Plain Talk, Clarion Macro Sentinel, Clarion Value Screener, Clarion Analyst, Clarion Thesis Architect, Clarion Portfolio Manager, Clarion LP Voice). -> - Rules installed in Zo Settings → AI: 8 Clarion rules (Rule 3 — live market data; Rules 5–10 — persona routing; Rule 11 — return to default). > - SEC EDGAR identification: `` (the actual value, not the placeholder). > -> Just ask me things like *"what's the market regime?"*, *"evaluate NVDA"*, *"update my watchlist"*, *"write a thesis on TTD"*, *"show me my portfolio"*, or *"update the Q1 letter"*. +> Try it out — ask me things like *"evaluate AAPL"*, *"what's the market regime?"*, *"index NVDA's latest 10-K"*, or *"run a value screen on AAPL, KO, JNJ"*. The skills work as standalone CLIs too. +> +> **Optional next step — install Clarion's persona routing for the full chat experience.** This adds the 7 Clarion personas (Macro Sentinel, Analyst, Thesis Architect, Portfolio Manager, etc.) and 8 routing rules that enforce regime-first framing, kill-condition discipline, and automatic persona handoff. Takes ~3 minutes. To opt in, just say: *"install Clarion personas and routing rules"*. To skip: do nothing — the skills above all work without it. -If anything in this report differs from the expected state (e.g., fewer than 7 personas, fewer than 8 rules, service not RUNNING, sec_user_agent is still the placeholder), call this out explicitly. Do not paper over partial-install state. +If anything in this report differs from the expected state (e.g., service not RUNNING, sec_user_agent is still the placeholder), call this out explicitly. Do not paper over partial-install state. ## Idempotency @@ -234,15 +190,15 @@ Re-running this skill is safe. Each step: - **Config.json**: preserved if present — including any `sec_user_agent` the user previously set. The setup script does NOT overwrite an existing config. - **Skill install**: each sibling `clarion-*` skill in `/home/workspace/Skills/` is refreshed (overwritten) with the upstream copy. This is the intended path to pull in upstream skill fixes after a `git pull`. - **Service registration**: if the user already has a `sec-indexer` service, `register_user_service` should report it exists; treat that as success and continue. -- **Persona install**: Step 4 calls `list_personas()` and asks the user before replacing any existing Clarion persona. User customizations are preserved unless the user opts in to replacement. The order is "ask first, then replace" — never silent overwrite. -- **Rule install**: Same — Step 5 calls `list_rules()` and asks before replacing. -- **Human checkpoint**: Step 6's Input A is skipped if `config.json` already has a non-placeholder `sec_user_agent`. Step 6's Input B is essentially "if the secret already exists, the user replies `done` immediately and the SKILL.md's USER_ACTION_REQUIRED message instructs them this is OK." +- **Human checkpoint**: Step 4's Input A is skipped if `config.json` already has a non-placeholder `sec_user_agent`. Step 4's Input B is essentially "if the secret already exists, the user replies `done` immediately and the SKILL.md's USER_ACTION_REQUIRED message instructs them this is OK." + +Personas and routing rules are not touched by re-runs because they're not installed by this skill. They live in Zo Settings → AI → Personas / Rules and are managed by the user (or by the separate persona-install prompt). A re-run of clarion-setup never adds, removes, or modifies personas or rules. ### Re-running to pick up source updates Editable installs (`uv pip install -e`) do NOT reload an already-running service — the `sec-indexer` process keeps the Python modules it imported at startup in memory. After a `git pull` brings in new code, you MUST restart the service for the changes to take effect. -If the user is re-running setup specifically to pull in upstream fixes, the existing Step 7b restart in this flow handles this naturally. After Step 8 verifies RUNNING, the new code is live. +If the user is re-running setup specifically to pull in upstream fixes, the existing Step 5b restart in this flow handles this naturally. After Step 6 verifies RUNNING, the new code is live. ## On error @@ -252,6 +208,4 @@ If any step fails, do not silently proceed. Read the error, summarize the cause, - **`uv: command not found`** — same. - **`uv pip install` fails with venv error** — the script tries `--system` automatically; if it still fails, ask the user to share the full error. - **`register_user_service` fails with a JSON-escaping or "runner stopped" error** — re-read the *env_vars formatting* guidance in Step 3. The most common cause is `env_vars` being passed as a stringified JSON instead of an object. Re-form the call and retry. -- **`create_persona` / `create_rule` returns an error** — surface the error verbatim. Possible causes include a tool-not-available environment, malformed prompt text (check the extracted code block for stray markdown), or a transient platform error (retry once before giving up). -- **`service_doctor` shows non-RUNNING after Step 7's restart** — follow the Step 8 troubleshooting (inspect entrypoint via `list_user_services()`, inspect logs, delete + re-register if entrypoint is corrupted). Do NOT mark setup complete. -- **The user replies "no" to replacing personas/rules in Step 4/5** — that's their right. Continue with the existing persona's ID in the map for Step 5's rule substitutions. The final report in Step 9 should mention which personas/rules were preserved vs. created. +- **`service_doctor` shows non-RUNNING after Step 5's restart** — follow the Step 6 troubleshooting (inspect entrypoint via `list_user_services()`, inspect logs, delete + re-register if entrypoint is corrupted). Do NOT mark setup complete. diff --git a/External/clarion-setup/scripts/setup.py b/External/clarion-setup/scripts/setup.py index 61ca805..68ce282 100644 --- a/External/clarion-setup/scripts/setup.py +++ b/External/clarion-setup/scripts/setup.py @@ -64,7 +64,11 @@ def _clarion_home() -> Path: DEFAULT_CONFIG: dict = { "indexing_model": "zo:openai/gpt-5.4-mini", "indexing_fallback_model": "zo:minimax/minimax-m2.5", - "reasoning_model": "zo:anthropic/claude-opus-4-7", + # Free-tier default per ARCHITECTURE.md "Default model selection" — a fresh install + # must run end-to-end on a free Zo account. Subscriber-tier models (e.g. + # zo:anthropic/claude-opus-4-7) are opt-in: edit this field in ~/clarion/config.json + # and restart the sec-indexer service. + "reasoning_model": "zo:openai/gpt-5.4-mini", "sec_user_agent": "Clarion Intelligence System (clarion@example.com)", "data_root": str(WORKSPACE), }