### Install and Start Local Development Server

Source: https://github.com/nyxfoundation/speca/blob/main/website/README.md

Install project dependencies and start the local development server for the Docusaurus site. Use the `-- --locale en` flag to serve the English locale.

```bash
npm install      # one-time
npm start        # http://localhost:3000 — JP locale only, fast HMR
npm start -- --locale en   # serve the English locale instead
```

--------------------------------

### Install speca-cli (Always-Fresh)

Source: https://github.com/nyxfoundation/speca/blob/main/cli/RELEASE_NOTES_v0.9.0.md

Recommended installation method for the 0.9.x preview to always use the latest version.

```bash
# Always-Fresh (recommended for the 0.9.x preview)
npx speca-cli@latest <command>
```

--------------------------------

### Install Dependencies

Source: https://github.com/nyxfoundation/speca/blob/main/scripts/datasets/README.md

Installs the necessary dependencies for the datasets group using uv.

```bash
uv sync --group datasets
```

--------------------------------

### Start the Web server

Source: https://github.com/nyxfoundation/speca/blob/main/website/i18n/en/docusaurus-plugin-content-docs/current/getting-started/web-ui-quickstart.md

Launch the Speca Web UI server. This command starts the server on a specified port and host, and serves the frontend application.

```bash
uv run speca-web --port 7411 --host 127.0.0.1 --serve-frontend
```

--------------------------------

### Verify CLI and MCP setup

Source: https://github.com/nyxfoundation/speca/blob/main/website/i18n/en/docusaurus-plugin-content-docs/current/guide/try-it.md

Run these commands to ensure that Python, Node.js, the 'claude' CLI, and the MCP server are correctly installed and configured. The `--verify` flag checks MCP registration.

```bash
# Python / Node / git / claude CLI / MCP server all present?
uv run python -c "import sys; print(sys.version)"
node --version
which claude    # or where claude on Windows
bash scripts/setup_mcp.sh --verify
```

--------------------------------

### Install speca-cli (Global)

Source: https://github.com/nyxfoundation/speca/blob/main/cli/RELEASE_NOTES_v0.9.0.md

Install speca-cli globally on your system.

```bash
# Global install
npm install -g speca-cli
```

--------------------------------

### Install or upgrade speca-cli

Source: https://github.com/nyxfoundation/speca/blob/main/cli/RELEASE_NOTES_v1.0.0.md

Always get the latest version or pin to a specific release. Global installation is also supported.

```bash
# Always-fresh
npx speca-cli@latest <command>

# Pin to this release
npx speca-cli@1.0.0 <command>

# Global install
npm install -g speca-cli
```

--------------------------------

### Install and Check SPECA CLI

Source: https://github.com/nyxfoundation/speca/blob/main/cli/README.md

Use these commands to install the SPECA CLI globally or check your environment.

```bash
npx speca-cli@latest doctor    # one-shot environment check
```

```bash
npm install -g speca-cli       # global install
```

--------------------------------

### Install SPECA from Source

Source: https://github.com/nyxfoundation/speca/blob/main/website/i18n/en/docusaurus-plugin-content-docs/current/getting-started/installation.md

Installs SPECA from its source code. This involves cloning the repository, installing Python dependencies, building the CLI front-end, and linking the binary.

```bash
git clone https://github.com/NyxFoundation/speca.git
cd speca

# Install Python deps for the orchestrator
uv sync

# Build the CLI front-end
cd cli && npm install && npm run build && cd ..

# Either link the built binary onto your PATH …
npm link --prefix cli

# … or invoke the local build directly
node cli/dist/cli.js doctor
```

--------------------------------

### Install GitHub Copilot CLI

Source: https://github.com/nyxfoundation/speca/blob/main/website/i18n/en/docusaurus-plugin-content-docs/current/operations/multi-runtime.md

Install the GitHub Copilot CLI globally using npm. The first launch will initiate GitHub OAuth for authentication.

```bash
npm install -g @github/copilot
copilot                       # First launch performs GitHub OAuth (creds in ~/.copilot)
```

--------------------------------

### Install SPECA CLI Globally

Source: https://github.com/nyxfoundation/speca/blob/main/website/i18n/en/docusaurus-plugin-content-docs/current/getting-started/installation.md

Installs the SPECA CLI globally using npm. After installation, the `speca` command will be available on your PATH.

```bash
# One-shot environment check (no install)
npx speca-cli@latest doctor

# Persistent install
npm install -g speca-cli
speca doctor
```

--------------------------------

### Check Prerequisites with CLI

Source: https://github.com/nyxfoundation/speca/blob/main/website/i18n/en/docusaurus-plugin-content-docs/current/guide/try-it.md

Verify that Node.js, Python (via uv), and Git are installed and meet the minimum version requirements.

```bash
node --version    # v20+
uv --version      # 0.6+
git --version
```

--------------------------------

### Traceability Example

Source: https://github.com/nyxfoundation/speca/blob/main/website/i18n/en/docusaurus-plugin-content-docs/current/concepts/worked-example.md

This example illustrates the traceability from a verdict to its originating specification section, showing the chain of IDs and links from the finding back to a specific URL in the documentation.

```text
04 verdict (FINDING-018)
   └─ property_id: PROP-101
       └─ covers: FN-042                      (01e → 01b)
           └─ spec_section_id: block-application  (01b → 01a)
               └─ url: eips.example.org/EIP-9999.md
```

--------------------------------

### Install speca-cli (Pin to Release)

Source: https://github.com/nyxfoundation/speca/blob/main/cli/RELEASE_NOTES_v0.9.0.md

Install a specific version of speca-cli, in this case, 0.9.0.

```bash
# Pin to this release
npx speca-cli@0.9.0 <command>
```

--------------------------------

### Install and Authenticate Gemini

Source: https://github.com/nyxfoundation/speca/blob/main/website/i18n/en/docusaurus-plugin-content-docs/current/operations/multi-runtime.md

Install the Gemini CLI and set your API key obtained from Google AI Studio. This key is used for authentication with the Gemini API.

```bash
npm install -g @google/gemini-cli
export GEMINI_API_KEY=...   # https://aistudio.google.com/apikey
```

--------------------------------

### Install Specific Python Version with uv

Source: https://github.com/nyxfoundation/speca/blob/main/website/i18n/en/docusaurus-plugin-content-docs/current/operations/troubleshooting.md

Use `uv python install` to get a specific Python version if `uv sync` fails due to a missing version. If issues persist, remove the virtual environment and retry `uv sync`.

```text
error: Could not find Python 3.12 ...
```

```bash
uv python install 3.12
uv sync
```

```bash
rm -rf .venv
uv sync
```

--------------------------------

### List Available Runtimes

Source: https://github.com/nyxfoundation/speca/blob/main/website/i18n/en/docusaurus-plugin-content-docs/current/operations/multi-runtime.md

Use the `run_phase.py` script to list all available AI runtimes and their current status (e.g., installation and authentication).

```bash
uv run python scripts/run_phase.py --list-runtimes
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/nyxfoundation/speca/blob/main/website/i18n/en/docusaurus-plugin-content-docs/current/guide/try-it.md

Clone the SPECA repository and install both Python and frontend dependencies. Includes troubleshooting for common installation issues on different operating systems.

```bash
git clone https://github.com/NyxFoundation/speca.git
cd speca

uv sync                          # Python deps
cd web/frontend && npm install   # Frontend deps
cd ../..
```

--------------------------------

### Serve Ollama and Set Host

Source: https://github.com/nyxfoundation/speca/blob/main/website/i18n/en/docusaurus-plugin-content-docs/current/operations/multi-runtime.md

Start the Ollama server for self-hosting and set the OLLAMA_HOST environment variable to point to your local Ollama instance.

```bash
ollama serve              # localhost:11434
ollama pull llama3.2
export OLLAMA_HOST=http://localhost:11434
```

--------------------------------

### CI Example: Nightly SPECA Audit with GitHub Actions

Source: https://github.com/nyxfoundation/speca/blob/main/website/i18n/en/docusaurus-plugin-content-docs/current/guide/try-it.md

This YAML configuration sets up a nightly audit using SPECA within a GitHub Actions workflow. It checks out code, sets up necessary tools (Node.js, uv, Claude CLI), installs dependencies, writes target and scope information, runs the SPECA audit, and uploads artifacts.

```yaml
name: Nightly SPECA audit
on:
  schedule: [{ cron: "0 18 * * *" }]   # 03:00 JST nightly
  workflow_dispatch: # Allows manual triggering

jobs:
  audit:
    runs-on: ubuntu-22.04
    timeout-minutes: 180
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: "20" }
      - uses: astral-sh/setup-uv@v3
      - name: install claude CLI
        run: npm install -g @anthropic-ai/claude-code
      - name: install deps
        run: uv sync
      - name: write target info
        run: |
          cat > outputs/TARGET_INFO.json <<EOF
          {"repository":"${{ github.repository }}","ref":"${{ github.sha }}","project_type":"smart_contract"}
          EOF
          cat > outputs/BUG_BOUNTY_SCOPE.json <<EOF
          {"in_scope_assets":["contracts/**/*.sol"],"spec_urls":[]}
          EOF
      - name: speca audit
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          uv run python scripts/run_phase.py \
            --target 04 \
            --workers 4 \
            --budget 50 \
            --json --no-tui > audit-events.ndjson
      - name: upload artifacts
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: speca-${{ github.run_id }}
          path: |
            outputs/
            audit-events.ndjson
            .speca/runs/

```

--------------------------------

### Install and Authenticate Codex

Source: https://github.com/nyxfoundation/speca/blob/main/website/i18n/en/docusaurus-plugin-content-docs/current/operations/multi-runtime.md

Install the Codex CLI and authenticate. Use 'codex login' for a ChatGPT plan subscription or 'codex login --with-api-key' if using an API key.

```bash
npm install -g @openai/codex

# Use a ChatGPT plan
codex login

# Or an API key
printenv OPENAI_API_KEY | codex login --with-api-key
```

--------------------------------

### Start Ollama Serve and Pull Model

Source: https://github.com/nyxfoundation/speca/blob/main/website/i18n/en/docusaurus-plugin-content-docs/current/operations/troubleshooting.md

Starts the Ollama server in the background and pulls a specified model. Use this if the Ollama server is not running or the required model is not downloaded.

```bash
ollama serve &
ollama pull llama3.2
```

--------------------------------

### Install and Authenticate Claude

Source: https://github.com/nyxfoundation/speca/blob/main/website/i18n/en/docusaurus-plugin-content-docs/current/operations/multi-runtime.md

Install the Claude CLI and authenticate using either OAuth or an API key. OAuth is for claude.ai Pro/Max subscribers, while API keys can be set via environment variable or directly in the UI.

```bash
npm install -g @anthropic-ai/claude-code
claude auth login        # claude.ai OAuth (Pro/Max) or API key
```

--------------------------------

### Register MCP Servers

Source: https://github.com/nyxfoundation/speca/blob/main/CLAUDE.md

Register MCP servers using the setup script. The `--verify` flag can be used to confirm the registration.

```bash
# Register MCP servers
bash scripts/setup_mcp.sh
```

```bash
bash scripts/setup_mcp.sh --verify
```

--------------------------------

### Check Node.js and UV versions

Source: https://github.com/nyxfoundation/speca/blob/main/website/i18n/en/docusaurus-plugin-content-docs/current/getting-started/web-ui-quickstart.md

Verify that Node.js and uv are installed and meet the minimum version requirements.

```bash
node --version
uv --version
```

--------------------------------

### Specification Traceability Matrix Example

Source: https://github.com/nyxfoundation/speca/blob/main/prompts/06b_audit_report.md

An example markdown table for the specification traceability section. Populate with requirement labels, descriptions, implementation concepts, test evidence, and finding references.

```markdown
| Requirement Label | Source Description | Implementation Concept | Test Evidence | Finding Reference |
|-------------------|--------------------|------------------------|---------------|-------------------|
| Shielded transfer must conserve supply | Derived from Privacy Token Spec §Supply Controls | Core token logic | Supply balance fuzzing campaign | Finding-02 |
| Merkle tree depth fixed to prevent overflow | Derived from Circuit Spec §Merkle Constraints | Proof circuit for inserts | Circuit property test | Gap-01 |
```

--------------------------------

### Sign in to Claude

Source: https://github.com/nyxfoundation/speca/blob/main/website/i18n/en/docusaurus-plugin-content-docs/current/getting-started/quickstart.md

Authenticates with Claude. This is a one-time setup step. It can either use an API key from `~/.config/speca/auth.json` or delegate to the `claude` session.

```bash
speca auth login
```

--------------------------------

### Run SPECA Web UI in Dev Mode (Bash)

Source: https://github.com/nyxfoundation/speca/blob/main/web/README.md

Starts the Python backend and the Vite dev server for local development. The Vite server proxies API requests to the backend.

```bash
# Terminal 1 — backend on http://127.0.0.1:7411
uv sync
uv run speca-web --port 7411 --no-open-browser

# Terminal 2 — Vite dev server with HMR on http://127.0.0.1:5173
# (proxies /api/* to the backend)
cd web/frontend
npm install
npm run dev
```

--------------------------------

### Run with GitHub Copilot Runtime

Source: https://github.com/nyxfoundation/speca/blob/main/website/i18n/en/docusaurus-plugin-content-docs/current/guide/try-it.md

Execute speca using the GitHub Copilot runtime. Install the Copilot CLI, perform OAuth, and optionally override the default model.

```bash
npm install -g @github/copilot
copilot                                # First launch performs GitHub OAuth (creds in ~/.copilot)
# Optional: COPILOT_MODEL=claude-sonnet-4-6 to override the CLI's default
uv run python scripts/run_phase.py --target 04 --runtime copilot --workers 2
```

--------------------------------

### Authenticate with Claude

Source: https://github.com/nyxfoundation/speca/blob/main/website/i18n/en/docusaurus-plugin-content-docs/current/guide/try-it.md

Install the Claude CLI and log in via OAuth to authenticate with Claude. Includes a command to check the authentication status.

```bash
npm install -g @anthropic-ai/claude-code
claude auth login        # opens claude.ai OAuth in the browser
```

```bash
claude auth status --json
# → { "loggedIn": true, "authMethod": "claude.ai", "email": "...", "subscriptionType": "max" }
```

--------------------------------

### Build and Serve Static Site

Source: https://github.com/nyxfoundation/speca/blob/main/website/README.md

Build a static version of the site for both locales or serve the built site locally. These commands are useful for testing the production build.

```bash
npm run build    # static build for both locales (used by CI)
npm run serve    # serve the built site locally
```

--------------------------------

### Install or Upgrade speca-cli

Source: https://github.com/nyxfoundation/speca/blob/main/cli/RELEASE_NOTES_v0.9.1.md

Commands for installing or upgrading speca-cli to the latest version or a specific release. Ensure Node.js 20+ is installed.

```bash
# Always-fresh
npx speca-cli@latest <command>

# Pin to this release
npx speca-cli@0.9.1 <command>

# Global install
npm install -g speca-cli
```

--------------------------------

### Run SPECA Web UI in Production-like Mode (Bash)

Source: https://github.com/nyxfoundation/speca/blob/main/web/README.md

Builds the frontend assets and runs the backend server, which serves the built SPA. The backend can also open the default browser on startup.

```bash
cd web/frontend
npm install
npm run build              # produces web/frontend/dist
cd ../..
uv run speca-web --port 7411 --serve-frontend
```

--------------------------------

### Bootstrap SPECA CLI with TUI

Source: https://github.com/nyxfoundation/speca/blob/main/README.md

Use these commands to check the toolchain, initialize configuration files, and run an audit using the TUI.

```bash
npx speca-cli@latest doctor

```

```bash
npx speca-cli@latest init

```

```bash
npx speca-cli@latest run --target 04

```

--------------------------------

### Audit Progress Stream Example

Source: https://github.com/nyxfoundation/speca/blob/main/website/i18n/en/docusaurus-plugin-content-docs/current/tutorial/audit-walkthrough.md

Example of the NDJSON output streamed during an audit, showing progress through different phases and findings.

```json
{"phase":"01a","status":"running","found":3}
```

```json
{"phase":"01b","status":"running","subgraph":"Ownable-ownership-transfer"}
```

```json
{"phase":"01e","status":"running","property":"PROP-001",
 "description":"onlyOwner is applied to all administrative functions"}
```

```json
{"phase":"02c","status":"running","resolved":5}
```

```json
{"phase":"03","status":"running","property":"PROP-001","result":"gap_found"}
```

```json
{"phase":"04","status":"running","verdict":"CONFIRMED_POTENTIAL"}
```

--------------------------------

### Run SPECA without global install

Source: https://github.com/nyxfoundation/speca/blob/main/website/i18n/en/docusaurus-plugin-content-docs/current/guide/faq.md

Execute SPECA commands using npx to avoid a global npm installation. Note the trade-off in per-invocation resolution time.

```bash
npx speca-cli@latest <subcommand>
```

--------------------------------

### Troubleshoot npm Install Hangs

Source: https://github.com/nyxfoundation/speca/blob/main/website/i18n/en/docusaurus-plugin-content-docs/current/operations/troubleshooting.md

If `npm install` hangs, verify your Node.js version is v20 or higher. Clear the npm cache, remove existing `node_modules` and `package-lock.json`, then reinstall.

```bash
node -v        # must be v20+
npm cache clean --force
rm -rf web/frontend/node_modules web/frontend/package-lock.json
cd web/frontend && npm install
```

--------------------------------

### Run with Google Gemini Runtime (API Key)

Source: https://github.com/nyxfoundation/speca/blob/main/website/i18n/en/docusaurus-plugin-content-docs/current/guide/try-it.md

Configure and run speca with the Google Gemini runtime using an API key. Set the `GEMINI_API_KEY` environment variable.

```bash
export GEMINI_API_KEY=...
uv run python scripts/run_phase.py --target 04 --runtime gemini
```

--------------------------------

### Run Doctor Command

Source: https://github.com/nyxfoundation/speca/blob/main/cli/RELEASE_NOTES_v0.9.1.md

Use this command to check the health and configuration of your speca-cli installation.

```bash
npx speca-cli@latest doctor
```

--------------------------------

### Update SPECA CLI

Source: https://github.com/nyxfoundation/speca/blob/main/website/i18n/en/docusaurus-plugin-content-docs/current/guide/faq.md

Update the global SPECA CLI to the latest version and verify the installation.

```bash
npm update -g speca-cli
speca doctor
```

--------------------------------

### Run with Ollama Self-Hosted

Source: https://github.com/nyxfoundation/speca/blob/main/website/i18n/en/docusaurus-plugin-content-docs/current/guide/try-it.md

Set up and run speca with a self-hosted Ollama instance. Ensure Ollama is running in one terminal and speca is configured to connect to it in another.

```bash
# Terminal A
ollama serve
ollama pull llama3.2
# Terminal B
export OLLAMA_HOST=http://localhost:11434
uv run python scripts/run_phase.py --target 04 --runtime ollama --workers 2
```

--------------------------------

### Configure Locales in Docusaurus

Source: https://github.com/nyxfoundation/speca/blob/main/website/README.md

Configure the default and available locales for the Docusaurus site. This setup enables bilingual support for the documentation.

```javascript
i18n: {
  defaultLocale: 'ja',
  locales: ['ja', 'en'],
}
```

--------------------------------

### Run SPECA End-to-End

Source: https://github.com/nyxfoundation/speca/blob/main/website/i18n/en/docusaurus-plugin-content-docs/current/operations/benchmark-rq2a.md

Commands to set up the dataset, run SPECA audits for different models, and perform evaluation and visualization. This process requires API costs.

```bash
# 1. Clone the RepoAudit dataset into target_workspace/
gh workflow run rq2a-01-setup-dataset.yml

# 2. Run SPECA (workflows are split per model)
gh workflow run rq2a-03-audit-map-sonnet4.yml -f projects=all
gh workflow run rq2a-03-audit-map-deepseek-r1.yml -f projects=all

# 3. Evaluation + visualization
gh workflow run rq2a-04-evaluate-sonnet4.yml -f projects=all
```

--------------------------------

### Run with Ollama Cloud

Source: https://github.com/nyxfoundation/speca/blob/main/website/i18n/en/docusaurus-plugin-content-docs/current/guide/try-it.md

Connect to the Ollama cloud service for running speca. Set the `OLLAMA_HOST` and `OLLAMA_API_KEY` environment variables.

```bash
export OLLAMA_HOST=https://ollama.com
export OLLAMA_API_KEY=...
uv run python scripts/run_phase.py --target 04 --runtime ollama
```

--------------------------------

### Initialize Speca Configuration (Non-interactive)

Source: https://github.com/nyxfoundation/speca/blob/main/website/i18n/en/docusaurus-plugin-content-docs/current/getting-started/quickstart.md

Initializes Speca configuration non-interactively using command-line flags. This is useful for scripting or automated setups.

```bash
speca init \
  --target-repo https://github.com/sigp/lighthouse \
  --target-commit v5.1.3 \
  --target-language Rust \
  --target-layer consensus \
  --rubric default \
  --non-interactive
```

--------------------------------

### Check Runtime Settings

Source: https://github.com/nyxfoundation/speca/blob/main/website/i18n/en/docusaurus-plugin-content-docs/current/operations/troubleshooting.md

Fetches the current runtime configuration from the API and displays the content of the local runtime.json file. Both should match to ensure settings are applied.

```bash
curl http://127.0.0.1:7411/api/runtime
cat ~/.speca/runtime.json
```

--------------------------------

### Execute Unit and Integration Tests

Source: https://github.com/nyxfoundation/speca/blob/main/prompts/06_report.md

Use these commands to run unit and integration tests for the project. Ensure the runner and arguments are correctly configured for your environment.

```bash
# Unit test
<runner_for_project> <args_to_run> {{UT_PATH}}
```

```bash
# Integration test (if present)
<runner_for_project> <args_to_run> {{IT_PATH}}
```

--------------------------------

### Mermaid State Diagram Example

Source: https://github.com/nyxfoundation/speca/blob/main/website/i18n/en/docusaurus-plugin-content-docs/current/pipeline/01b-subgraph-extraction.md

Illustrates the structure of a Mermaid state diagram generated from specification documents, including states, transitions, and invariant notes.

```mermaid
stateDiagram-v2
  [*] --> StateA
  StateA --> StateB: transition_label
  StateB --> [*]
  
  note right of StateA
    INV-001: Property X must hold
    INV-002: Invariant Y
  end note
```

--------------------------------

### Build Derived Dataset for New Domain

Source: https://github.com/nyxfoundation/speca/blob/main/scripts/datasets/README.md

Perform a local dry-run to build the derived dataset for a new domain, like Ethereum. This requires specifying the domain, the source CSV file path, and disabling the platform allow-list.

```bash
uv run --group datasets python3 scripts/datasets/build_derived.py \
  --domain ethereum \
  --source benchmarks/data/ethereum_past_fixes/<crawler>.csv \
  --filter-platforms '' \
  --out-dir dist/datasets
```

--------------------------------

### Proof Gap Example

Source: https://github.com/nyxfoundation/speca/blob/main/website/i18n/en/docusaurus-plugin-content-docs/current/concepts/proof-attempt.md

Shows a concrete 'proof gap' identified by SPECA, including the claim, the location of the gap, and the specific code causing the issue.

```plaintext
Claim: "authenticate() is called before sensitive_data()"

Gap at line 85 in error_handler():
  if (!cache_hit) {
    sensitive_data();  // <-- authenticate() not called
  }
```