Vulcan Analyst Guide

Vulcan Analyst is a local-first CLI for inspecting Vulcan workspaces and guiding Home Energy Model analysis with an AI harness.

This guide describes the current command surface. Check inputs and outputs carefully before relying on AI-generated suggestions, especially where model files, scenario definitions, evidence, or compliance decisions are involved.

1. Requirements

• A Vulcan workspace created by the browser app.
• Node.js 22.19.0 or later for the Analyst package and chat harness.
• npm.
• A terminal with access to the local workspace folder.
• A Vulcan account when the Analyst auth route is enabled.

The browser app still requires a Chromium-based browser for normal workspace setup because it uses the File System Access API. Analyst works from the same files after they exist on disk.

2. Install Analyst

Install Analyst only from the package or instructions supplied by Vulcan.

When the npm package is available, install it globally:

npm install -g @vulcan-energy/analyst

For internal development from the monorepo, build the workspace package first:

npm run build --workspace @vulcan-energy/analyst

Then run the CLI from the package or linked binary:

vulcan-analyst commands

If chat fails before startup, check the Node version first:

node --version

3. Login and auth expectation

The production target is:

vulcan-analyst login

That flow is expected to open the browser, use the existing Vulcan login, and store revocable device credentials outside the assessment workspace.

Current status:

• vulcan-analyst login is not yet implemented.
• The CLI must not ask for your Vulcan password in the terminal.
• Credentials must not be stored in the assessment workspace.
• Access is expected to be limited to authenticated Vulcan users once the token route is available.
• Vulcan-paid inference is out of scope until online spend checks are implemented.

4. Bring your own model keys

Analyst is designed for BYO model credentials or harness-provided model auth. Do not save model API keys inside a Vulcan workspace or commit them to project files.

Current status:

• BYO model-key configuration is not locked yet.
• The current Pi SDK harness path uses in-memory auth, settings, and session managers by default.
• The default model target in the harness code is Anthropic Claude Sonnet 4, but a usable key/provider setup still depends on the approved setup instructions.
• If a model provider requires an environment variable or local credential store, configure it outside the Vulcan workspace.

5. Workspace paths

Analyst works with the same local workspace structure used by the browser app and MCP Helper. Typical paths include:

<workspace>/
  input/
    base_models/
      <model>.csv
    defaults/
      *.json
    batch_parameters/
    batch_configs/
  output/

You can point Analyst at either the workspace folder or a specific geometry CSV.

Use a workspace folder when you want Analyst to resolve standard project paths:

vulcan-analyst inspect /path/to/vulcan-workspace

Use a CSV path when you want to inspect one model:

vulcan-analyst inspect /path/to/vulcan-workspace/input/base_models/model.csv

Optional flags let you override detection:

vulcan-analyst inspect /path/to/model.csv \
  --workspace /path/to/vulcan-workspace \
  --csv /path/to/model.csv \
  --schema /path/to/input_fhs.schema.json \
  --defaults /path/to/defaults.json

Avoid /Users/... paths in shared notes, scripts, or docs. Use project-relative paths when you are recording evidence for other people.

6. Inspect a model

inspect is the stable read-only command available today.

vulcan-analyst inspect <workspace-or-csv-path>

It currently:

• detects the workspace or CSV target;
• resolves the CSV DefaultsPath using browser-equivalent rules;
• runs the browser WASM conversion artifact in memory;
• applies the Rust-authoritative UI-only field stripping boundary;
• reports schema/defaults sources, validation status, and a HEM JSON summary;
• reports that no files were written;
• reports model-provider request count for the inspect path.

For machine-readable output:

vulcan-analyst inspect <workspace-or-csv-path> --json

The text output includes lines similar to:

Vulcan Analyst inspect: ok
Workspace: /path/to/workspace
CSV: /path/to/workspace/input/base_models/model.csv
Files written: no
Model requests: 0

7. Chat harness status

chat is the experimental conversational path:

vulcan-analyst chat <workspace-or-csv-path>

Current status:

• The command starts a Vulcan-owned line-stream shell path when run without --json.
• The JSON mode is a readiness check:

vulcan-analyst chat <workspace-or-csv-path> --json

• The shell verifies the active and registry-visible tool policy before accepting input.
• The default analyst profile exposes only vulcan_inspect.
• The advanced and developer profiles are scaffolds; raw Pi read, bash, edit, write, grep, find, and ls tools remain hidden.
• Local shell commands include /help, /tools, /profile, /abort, and /exit.

The chat harness is not the same as an unrestricted coding agent. Treat it as experimental until the model-provider, approval, branding, and evidence-log flows are complete.

8. Data egress

Analyst should make remote data movement visible.

Current behavior:

• inspect runs locally and reports model_provider_requests: 0.
• inspect returns compact structured output rather than uploading whole assessment files by default.
• chat may send user prompts and selected tool output to the configured model provider once a model session is active.
• Session metadata should record the model/provider and remote data categories when session logging is enabled.

Before using chat on a real project, check:

• which model provider is configured;
• whether prompts include project-specific or personal data;
• which tool outputs are being sent to the model;
• where any session log is written.

9. Evidence logs

The intended evidence-log location is:

<workspace>/.vulcan/analyst/sessions/<session-id>.jsonl

Evidence events can include:

• chat harness startup and readiness;
• resource-loader requests;
• tool-registry verification;
• tool calls and tool results;
• local chat shell commands;
• prompt failures or shell exit status.

Current status:

• inspect itself is read-only and does not create an evidence-log file.
• chat creates a workspace evidence log unless an in-memory logger is injected by tests or development harnesses.
• Evidence logs can contain file paths, prompt metadata, tool result summaries, and provider/model metadata. Review them before sharing.

10. Current limitations

• vulcan-analyst login is planned but not implemented.
• BYO model-key setup is not yet finalized.
• Source and docs corpus citation tools are planned but not yet complete.
• inspect does not yet report source, docs, and manifest hashes in the full target form.
• Batch execution, result summarisation, and controlled writes are planned later phases.
• The default chat profile exposes only vulcan_inspect.
• Advanced and developer profiles do not yet expose scoped read/write/run capabilities.
• Raw Pi coding tools are intentionally hidden for normal Analyst users.
• Terminal branding and stock third-party language audit are not complete.
• Cross-platform clean-machine install tests are still pending.

11. Related docs

• Setting up Vulcan Software
• Vulcan MCP Server Guide
• Build Geometry section guide