schema: command-catalog/v1
generated: '2025-10-26T00:00:00Z'
owner: ChefDevAI
notes:
  - Aggregates pnpm scripts, shell helpers, and governance tools exposed in the unified-mandala
    repository.
  - Use pnpm run <script> to execute workspace commands unless a direct shell invocation
    is provided.
categories:
  - key: runtime
    title: Runtime & Developer Services
    description: Commands for launching dev servers, stacks, and runtime utilities.
    entries:
      - id: runtime.dev-stack
        name: Start dev stack
        command: pnpm dev:stack
        type: pnpm
        runs: node scripts/dev-services.mjs --mode=dev
        description: Starts the dev stack orchestrator; auto-frees default ports and checks availability.
        source:
          - package.json#scripts.dev:stack
          - scripts/dev-services.mjs
      - id: runtime.dev-ui
        name: UI dev server
        command: pnpm dev:ui
        type: pnpm
        runs: pnpm -F mandala-ui dev
        description: Launches the mandala-ui workspace dev server.
        source:
          - package.json#scripts.dev:ui
      - id: runtime.start-ollama-proxy
        name: Start Ollama proxy (API Lite)
        command: pnpm start:ollama-proxy
        type: pnpm
        runs: node apps/api-lite/ollama-proxy.mjs
        description: Starts the lightweight API proxy with /health and /metrics endpoints.
        source:
          - package.json#scripts.start:ollama-proxy
          - apps/api-lite/ollama-proxy.mjs
      - id: runtime.dev-ports-free
        name: Free common dev ports
        command: pnpm dev:ports:free
        type: pnpm
        runs: pnpm dlx kill-port 3001 3002 3003 3004 4020 4021
        description: Frees default ports before starting the dev stack.
        source:
          - package.json#scripts.dev:ports:free
      - id: runtime.start-verified
        name: Start verified stack (UI+stack+health)
        command: pnpm start:verified
        type: pnpm
        runs: tsx scripts/start-verified.ts
        description: Starts UI (Vite), dev stack and health aggregator, waits for readiness, then runs smoke:live. Respects PORT_OFFSET.
        source:
          - package.json#scripts.start:verified
          - scripts/start-verified.ts
  - key: smokes
    title: Smoke Tests
    description: Quick smoke commands for common subsystems.
    entries:
      - id: smoke.qwen
        name: Qwen smoke
        command: pnpm smoke:qwen
        type: pnpm
        runs: node scripts/smoke/qwen-smoke.mjs
        description: Runs UI + /api/ai/chat proxy smoke validation for Qwen profile.
        source:
          - package.json#scripts.smoke:qwen
      - id: smoke.fs
        name: FS smoke
        command: pnpm smoke:fs
        type: pnpm
        runs: node scripts/smoke/fs-smoke.mjs
        description: Filesystem tooling smoke.
        source:
          - package.json#scripts.smoke:fs
      - id: smoke.memory
        name: Memory smoke
        command: pnpm smoke:memory
        type: pnpm
        runs: node scripts/smoke/memory-smoke.mjs
        description: Memory tooling smoke.
        source:
          - package.json#scripts.smoke:memory
      - id: smoke.rag
        name: RAG smoke
        command: pnpm smoke:rag
        type: pnpm
        runs: node scripts/smoke/rag-smoke.mjs
        description: Retrieval augmented generation smoke.
        source:
          - package.json#scripts.smoke:rag
  - key: setup
    title: Setup & Environment
    description: Bootstrap developer workstations and core tooling parity.
    entries:
      - id: setup.dev-env
        name: Setup development environment (Linux/macOS)
        command: ./scripts/setup-dev-env.sh
        type: shell
        runs: ./scripts/setup-dev-env.sh
        description: Installs system packages, configures git, provisions a Python venv,
          and installs Node dependencies on Linux/macOS.
        source:
          - scripts/setup-dev-env.sh
      - id: setup.dev-env-windows
        name: Setup development environment (Windows)
        command: pwsh -NoProfile -File ./scripts/setup-dev-env.ps1
        type: powershell
        runs: pwsh -NoProfile -File ./scripts/setup-dev-env.ps1
        description: 'Installs Git, Node.js, and Python on Windows, enables Corepack with
          admin detection (non-admin → user activation), recognises Docker-managed `nats`
          containers (status + start hints) and runs pnpm using PowerShell 7+ (fallback:
          powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\setup-dev-env.ps1).'
        source:
          - scripts/setup-dev-env.ps1
      - id: setup.corepack-enable
        name: Enable Corepack
        command: corepack enable
        type: shell
        runs: corepack enable
        description: Activates Corepack so pnpm can be managed and pinned via Node's package
          manager shim.
        source:
          - DevTalk.txt#DevTalkPart5
      - id: setup.corepack-prepare-pnpm
        name: Activate pnpm 10.17.0
        command: corepack prepare pnpm@10.17.0 --activate
        type: shell
        runs: corepack prepare pnpm@10.17.0 --activate
        description: Downloads and activates pnpm 10.17.0 to match the Windows validation
          run.
        source:
          - DevTalk.txt#DevTalkPart5
      - id: setup.corepack-install-frozen
        name: Install workspace (frozen lockfile)
        command: corepack pnpm install --frozen-lockfile
        type: pnpm
        runs: corepack pnpm install --frozen-lockfile
        description: Installs pnpm workspace dependencies using the frozen lockfile for
          deterministic Windows parity.
        source:
          - DevTalk.txt#DevTalkPart5
      - id: setup.pnpm-install
        name: Install PNPM workspace
        command: pnpm install
        type: pnpm
        runs: pnpm install
        description: Installs Node dependencies across the pnpm workspace.
        source:
          - package.json#scripts
      - id: setup.poetry-install
        name: Install Python tooling
        command: poetry install --with test
        type: poetry
        runs: poetry install --with test
        description: Sets up Python dependencies including optional test extras.
        source:
          - pyproject.toml
      - id: setup.store-commit-memory
        name: Persist pnpm store snapshot
        command: pnpm store:commit-memory
        type: pnpm
        runs: pnpm store:commit-memory
        description: Runs Genesis ZIP memory bridge to persist dependency store metadata
          during first commit of a session.
        source:
          - package.json#scripts.store:commit-memory
      - id: setup.prepare-husky
        name: Install Husky hooks
        command: pnpm postinstall
        type: pnpm
        runs: husky
        description: Runs Husky's installer via the postinstall script (triggered by pnpm
          install).
        source:
          - package.json#scripts.postinstall
      - id: setup.labels-bootstrap
        name: Ensure provenance & CI labels
        command: pnpm labels:setup
        type: pnpm
        runs: node scripts/repo/setup-labels.mjs
        description: Bootstrap or refresh `source:*` and CI labels via GitHub CLI (gh
          label create/edit).
        source:
          - scripts/repo/setup-labels.mjs
          - package.json#scripts.labels:setup
      - id: setup.build-windows-tools
        name: Build Windows helper binaries
        command: pnpm build:windows-tools
        type: pnpm
        runs: node scripts/run-powershell.mjs tools/windows/build-windows-tools.ps1
        description: Invokes the Windows tooling build via Node wrapper that selects pwsh
          or Windows PowerShell when pwsh is unavailable.
        source:
          - package.json#scripts.build:windows-tools
      - id: setup.install-puppeteer-chrome
        name: Install Puppeteer Chrome shell
        command: pnpm exec puppeteer browsers install chrome-headless-shell
        type: pnpm
        runs: pnpm exec puppeteer browsers install chrome-headless-shell
        description: Installs the headless Chrome binary expected by @mermaid-js/mermaid-cli
          for Mermaid rendering on Windows.
        source:
          - DevTalk.txt#Fraktal60
      - id: setup.install-cypress
        name: Install Cypress binary
        command: pnpm exec cypress install
        type: pnpm
        runs: pnpm exec cypress install
        description: Installs the repo-pinned Cypress release (14.5.1) ahead of `pnpm
          cy:run` to avoid version mismatches or runtime prompts.
        source:
          - DevTalk.txt#Fraktal60
      - id: setup.docker-core
        name: Start core Docker profile
        command: docker compose --profile core up
        type: docker
        runs: docker compose --profile core up
        description: Bootstraps the core service stack with Docker Compose profiles described
          in the stabilization playbook.
        source:
          - docs/roadmap/v1.0-stabilization-playbook.md
      - id: setup.docker-prod
        name: Start production Docker drill
        command: docker compose --profile prod up
        type: docker
        runs: docker compose --profile prod up
        description: Runs the production simulation profile used during release drills.
        source:
          - docs/roadmap/v1.0-stabilization-playbook.md
  - key: quality
    title: Linting & Static Analysis
    description: Static type safety, linting, and formatting commands.
    entries:
      - id: quality.lint
        name: Workspace lint
        command: pnpm lint
        type: pnpm
        runs: pnpm lint:types && pnpm lint:eslint
        description: Aggregates TypeScript type checks and ESLint analysis with zero-warning
          enforcement.
        source:
          - package.json#scripts.lint
      - id: quality.lint-types
        name: TypeScript project check
        command: pnpm lint:types
        type: pnpm
        runs: tsc -p tsconfig.json --noEmit
        description: Ensures the workspace TypeScript configuration passes without emitting
          artifacts.
        source:
          - package.json#scripts.lint:types
      - id: quality.lint-eslint
        name: ESLint check
        command: pnpm lint:eslint
        type: pnpm
        runs: eslint "{scripts,services,src,tests}/**/*.{ts,tsx,js,jsx,cjs,mjs}" --max-warnings=0
          --cache
        description: Runs ESLint over scripts, services, source, and tests with caching
          enabled.
        source:
          - package.json#scripts.lint:eslint
      - id: quality.format
        name: Format workspace docs
        command: pnpm format
        type: pnpm
        runs: prettier --write README.md CONTRIBUTING.md docs/ONBOARDING.md codexfeedback.*
          scripts/dev-services.mjs
        description: Applies Prettier formatting to key documentation and service scripts.
        source:
          - package.json#scripts.format
      - id: quality.format-check
        name: Check formatting
        command: pnpm format:check
        type: pnpm
        runs: prettier --check README.md CONTRIBUTING.md docs/ONBOARDING.md codexfeedback.*
          scripts/dev-services.mjs
        description: Validates Prettier compliance without modifying files.
        source:
          - package.json#scripts.format:check
      - id: quality.lint-staged
        name: Run lint-staged
        command: pnpm lint-staged
        type: pnpm
        runs: lint-staged
        description: Executes lint-staged against staged files via Husky.
        source:
          - package.json#scripts.lint-staged
      - id: quality.check-precommit
        name: Pre-commit gate
        command: pnpm check:precommit
        type: pnpm
        runs: pnpm lint-staged && pnpm typecheck && pnpm test:unit && pnpm schema:validate
          && pnpm maps:validate && pnpm repomap:build && pnpm repomap:validate && pnpm
          sanity && pnpm policy:check
        description: Mirrors the Husky pre-commit hook; set `UM_SKIP_HEAVY_HOOKS=1` to
          execute lint-staged only.
        source:
          - package.json#scripts.check:precommit
      - id: quality.check-prepush
        name: Pre-push gate
        command: pnpm check:prepush
        type: pnpm
        runs: pnpm test:unit:coverage && pnpm policy:check
        description: Local mirror of the pre-push hook (coverage + policy suite with analytics
          disabled).
        source:
          - package.json#scripts.check:prepush
      - id: quality.check-ci
        name: Combined CI gate
        command: pnpm check:ci
        type: pnpm
        runs: pnpm typecheck && pnpm test:unit && pnpm schema:validate && pnpm maps:validate
          && pnpm repomap:build && pnpm repomap:validate && pnpm sanity && pnpm policy:check
        description: Aggregates the CI gates used by check-ci.yml for quick local verification.
        source:
          - package.json#scripts.check:ci
      - id: quality.ci-fast-checks
        name: Fast CI checks
        command: pnpm ci:fast-checks
        type: pnpm
        runs: pnpm -w -r exec -- npx tsc -p tsconfig.json --noEmit && npx pyright -p .
        description: Runs distributed TypeScript checks and Pyright across the workspace
          for CI smoke coverage.
        source:
          - package.json#scripts.ci:fast-checks
      - id: quality.ai-commit-guard
        name: AI commit guard
        command: node scripts/ci/ai-commit-guard.mjs
        type: node
        runs: node scripts/ci/ai-commit-guard.mjs
        description: Enforces the two-plane policy by blocking `.ai-scratch/` artifacts
          and bot pushes on main; consumed by `ai-commit-guard.yml`.
        source:
          - scripts/ci/ai-commit-guard.mjs
          - .github/workflows/ai-commit-guard.yml
      - id: quality.status-gate
        name: Ready-to-merge status gate
        command: gh workflow run status-gate -f pr=<nummer>
        type: gh
        runs: gh workflow run status-gate -f pr=<nummer>
        description: Manual trigger for `status-gate.yml`; re-checks Draft, ReviewDecision,
          Mergeability and Status-Rollup before auto-merging/queuing a PR.
        source:
          - .github/workflows/status-gate.yml
      - id: quality.pyright
        name: Run Pyright
        command: npx pyright
        type: node
        runs: npx pyright
        description: Performs static type analysis for Python adapters using the Node
          Pyright CLI.
        source:
          - AGENTS.md
      - id: quality.tsc-no-emit
        name: Standalone TypeScript check
        command: npx tsc -p tsconfig.json --noEmit
        type: node
        runs: npx tsc -p tsconfig.json --noEmit
        description: Standalone invocation of the TypeScript compiler with no emit for
          quick verification.
        source:
          - package.json#scripts.lint:types
      - id: quality.tsc-build-pnpm
        name: TypeScript build via pnpm exec
        command: pnpm exec tsc -p tsconfig.build.json
        type: pnpm
        runs: pnpm exec tsc -p tsconfig.build.json
        description: Runs the TypeScript compiler through pnpm exec to ensure Windows
          shells resolve the local tsc binary.
        source:
          - DevTalk.txt#DevTalkPart5
  - key: testing
    title: Testing & Coverage
    description: Unit, integration, and regression test commands.
    entries:
      - id: testing.test
        name: Vitest run
        command: pnpm test
        type: pnpm
        runs: vitest run
        description: Runs the default Vitest suite.
        source:
          - package.json#scripts.test
      - id: testing.test-unit
        name: Unit test suite
        command: pnpm test:unit
        type: pnpm
        runs: vitest run
        description: Unit test suite with workspace defaults.
        source:
          - package.json#scripts.test:unit
      - id: testing.test-coverage
        name: Unit tests with coverage
        command: pnpm test:unit:coverage
        type: pnpm
        runs: vitest run --coverage
        description: Unit test suite with v8 coverage enabled.
        source:
          - package.json#scripts.test:unit:coverage
      - id: testing.test-membrane
        name: Membrane/KPI focused suite
        command: pnpm test:membrane
        type: pnpm
        runs: vitest run --reporter=dot tests/kpi/membrane-bridge.test.ts src/kpi/tests/membrane-bridge.test.ts tests/membrane/index.test.ts tests/membrane/real-membrane.test.ts
        description: Runs the focused Membrane/KPI suites for fast iteration.
        source:
          - package.json#scripts.test:membrane
      - id: testing.test-watch
        name: Vitest watch
        command: pnpm test:watch
        type: pnpm
        runs: vitest
        description: Starts Vitest in watch mode.
        source:
          - package.json#scripts.test:watch
      - id: testing.test-unit
        name: Vitest unit suite
        command: pnpm test:unit
        type: pnpm
        runs: vitest run
        description: Runs the Vitest unit suite without generating coverage reports for
          faster local feedback.
        source:
          - package.json#scripts.test:unit
      - id: testing.test-unit-coverage
        name: Vitest coverage suite
        command: pnpm test:unit:coverage
        type: pnpm
        runs: vitest run --coverage
        description: Executes Vitest with coverage reporting enabled; CI Core publishes
          the `coverage-vitest` artifact from this run.
        source:
          - package.json#scripts.test:unit:coverage
      - id: testing.test-jest
        name: Legacy Jest tests
        command: pnpm test:jest
        type: pnpm
        runs: echo "(Jest deaktiviert – nutze vitest)" && exit 0
        description: Legacy alias that prints a Vitest migration hint (Jest disabled).
        source:
          - package.json#scripts.test:jest
      - id: testing.test-agents
        name: Agents Vitest suite
        command: pnpm test:agents
        type: pnpm
        runs: vitest run
        description: Executes tests scoped to agent modules.
        source:
          - package.json#scripts.test:agents
      - id: testing.test-adapters
        name: Adapter decorators test
        command: pnpm test:adapters
        type: pnpm
        runs: vitest run src/adapters/tests/decorators.test.ts
        description: Runs targeted adapter decorator tests.
        source:
          - package.json#scripts.test:adapters
      - id: testing.test-ts
        name: TypeScript Vitest suite
        command: pnpm test:ts
        type: pnpm
        runs: vitest run --config vitest.config.ts
        description: Executes the TypeScript Vitest configuration.
        source:
          - package.json#scripts.test:ts
      - id: testing.test-ts-ci
        name: CI TypeScript tests
        command: pnpm test:ts:ci
        type: pnpm
        runs: NODE_OPTIONS=--max-old-space-size=2048 vitest run --config vitest.config.ts
        description: Vitest run tuned for CI memory constraints.
        source:
          - package.json#scripts.test:ts:ci
      - id: testing.test-jetstream
        name: JetStream bus test
        command: pnpm test:jetstream
        type: pnpm
        runs: vitest run --config vitest.config.ts --reporter=default tests/event-bus/jetstream-bus.test.ts
        description: Executes the JetStream bus contract test via Vitest (migrated from
          Jest).
        source:
          - package.json#scripts.test:jetstream
      - id: testing.test-ts-extended
        name: Extended TS suite
        command: pnpm test:ts:extended
        type: pnpm
        runs: cross-env ENABLE_EXTENDED_TESTS=1 vitest run --config vitest.config.ts
        description: Runs the extended TypeScript Vitest matrix.
        source:
          - package.json#scripts.test:ts:extended
      - id: testing.test-ts-experimental
        name: Experimental TS suite
        command: pnpm test:ts:experimental
        type: pnpm
        runs: cross-env ENABLE_EXTENDED_TESTS=1 ENABLE_EXPERIMENTAL_TESTS=1 vitest run
          --config vitest.config.ts
        description: Executes experimental TypeScript tests gated by feature flags.
        source:
          - package.json#scripts.test:ts:experimental
      - id: testing.test-py
        name: Pytest baseline
        command: pnpm test:py
        type: pnpm
        runs: node scripts/run-pytest.mjs
        description: Launches pytest via the repo resolver; defaults to -m "not slow and
          not experimental" -q.
        source:
          - package.json#scripts.test:py
      - id: testing.test-py-extended
        name: Extended Pytest
        command: pnpm test:py:extended
        type: pnpm
        runs: cross-env UM_PYTEST_MARK="not experimental" node scripts/run-pytest.mjs
        description: Uses the run-pytest wrapper with the extended marker and venv path
          resolution.
        source:
          - package.json#scripts.test:py:extended
      - id: testing.test-py-all
        name: Full Pytest
        command: pnpm test:py:all
        type: pnpm
        runs: node scripts/run-pytest.mjs -q
        description: Executes the full pytest suite in quiet mode without the default
          marker filter.
        source:
          - package.json#scripts.test:py:all
      - id: testing.test-py-venv-python
        name: Pytest via python.exe (Windows)
        command: .\.venv\Scripts\python.exe -m pytest -q
        type: powershell
        runs: .\.venv\Scripts\python.exe -m pytest -q
        description: Launches Pytest through the repository virtual environment so Windows
          shells do not rely on PATH lookups.
        source:
          - DevTalk.txt#Fraktal60
      - id: testing.test-py-venv-cli
        name: Pytest via CLI shim (Windows)
        command: .\.venv\Scripts\pytest.exe -q
        type: powershell
        runs: .\.venv\Scripts\pytest.exe -q
        description: Directly invokes the Pytest console script generated inside the virtualenv
          as an alternative to `python -m`.
        source:
          - DevTalk.txt#Fraktal60
      - id: testing.test-sigil
        name: Sigil CLI test
        command: pnpm test:sigil
        type: pnpm
        runs: node scripts/run-dist.mjs scripts/validate-sigil-cli.ts
        description: Validates the sigil CLI over sample fixtures.
        source:
          - package.json#scripts.test:sigil
      - id: testing.test-ui
        name: UI smoke tests
        command: pnpm test:ui
        type: pnpm
        runs: vitest run --passWithNoTests
        description: Runs UI-targeted Vitest suite tolerant to empty spec sets.
        source:
          - package.json#scripts.test:ui
      - id: testing.test-unit-coverage
        name: CI verification
        command: pnpm ci:verify
        type: pnpm
        runs: node scripts/ci-verify.mjs
        description: Runs the CI aggregator (Typecheck, Unit, Coverage, Schema/Map/Sanity,
          Policy) used by `ci-verify.yml`.
        source:
          - package.json#scripts.ci:verify
          - scripts/ci-verify.mjs
      - id: testing.qa
        name: QA regression suite
        command: pnpm qa
        type: pnpm
        runs: node scripts/run-dist.mjs scripts/qa-test-runner.ts
        description: Runs the QA orchestrator over prioritized checks.
        source:
          - package.json#scripts.qa
      - id: testing.qa-gpt5
        name: QA GPT-5 configuration
        command: pnpm qa:gpt5
        type: pnpm
        runs: node scripts/run-dist.mjs scripts/qa-test-runner.ts scripts/qa-gpt5.json
        description: Executes QA runner using the GPT-5 scenario manifest.
        source:
          - package.json#scripts.qa:gpt5
      - id: testing.cy-run
        name: Cypress run
        command: pnpm cy:run
        type: pnpm
        runs: cypress run
        description: Starts Cypress end-to-end tests.
        source:
          - package.json#scripts.cy:run
  - key: build_docs
    title: Build & Documentation
    description: Build pipelines, documentation exporters, and release assets.
    entries:
      - id: build.build
        name: Workspace build
        command: pnpm build
        type: pnpm
        runs: tsc -p tsconfig.build.json && pnpm build:agents
        description: Builds the TypeScript workspace and agent bundle artifacts.
        source:
          - package.json#scripts.build
      - id: build.build-recursive
        name: Workspace build (recursive)
        command: pnpm -w -r build
        type: pnpm
        runs: pnpm -w -r build
        description: Runs the build script across all workspaces using pnpm recursive
          mode (mirrors Windows verification flow).
        source:
          - DevTalk.txt#DevTalkPart5
      - id: build.build-agents
        name: Compile agents
        command: pnpm build:agents
        type: pnpm
        runs: tsc -p tsconfig.agents.json && node -e ...
        description: Compiles agent TypeScript and normalizes CommonJS outputs.
        source:
          - package.json#scripts.build:agents
      - id: build.build-ui
        name: Build Mandala UI
        command: pnpm build:ui
        type: pnpm
        runs: pnpm -F mandala-ui build
        description: Generates the UI distribution bundle via the mandala-ui workspace.
        source:
          - package.json#scripts.build:ui
      - id: build.docs-build
        name: Generate Typedoc
        command: pnpm docs:build
        type: pnpm
        runs: typedoc
        description: Builds API documentation via TypeDoc.
        source:
          - package.json#scripts.docs:build
      - id: build.docs-auto
        name: Auto-generate API docs
        command: pnpm docs:auto
        type: pnpm
        runs: node scripts/generate-api-docs.js
        description: Generates API documentation with custom script automation.
        source:
          - package.json#scripts.docs:auto
      - id: build.generate-changelog
        name: Generate changelog
        command: pnpm generate:changelog
        type: pnpm
        runs: node scripts/generate-changelog.js
        description: Outputs changelog entries from commit metadata.
        source:
          - package.json#scripts.generate:changelog
      - id: build.compile-agents-manifest
        name: Compile agents manifest
        command: pnpm compile:agents-manifest
        type: pnpm
        runs: node scripts/compile_agents_manifest.js
        description: Assembles the consolidated agents manifest for documentation.
        source:
          - package.json#scripts.compile:agents-manifest
      - id: build.export-crep-docs
        name: Export CREP docs
        command: pnpm export:crep-docs
        type: pnpm
        runs: node scripts/export-crep-docs.js
        description: Generates CREP documentation artifacts.
        source:
          - package.json#scripts.export:crep-docs
      - id: build.export-depth-bundle
        name: Export depth bundle
        command: pnpm export_depth_bundle
        type: pnpm
        runs: node scripts/run-dist.mjs scripts/export-depth-bundle.ts
        description: Creates Sigillin depth bundles and related media artifacts.
        source:
          - package.json#scripts.export_depth_bundle
      - id: build.generate-next-sigil
        name: Generate next sigil
        command: pnpm generate:next-sigil
        type: pnpm
        runs: node scripts/generate-next-sigil.js
        description: Produces the next sigil candidate and updates indices.
        source:
          - package.json#scripts.generate:next-sigil
      - id: build.generate-agents-diagram
        name: Generate agents diagram
        command: pnpm generate:agents-diagram
        type: pnpm
        runs: node scripts/generate-agents-diagram.js
        description: Creates Mermaid diagrams documenting the agent network.
        source:
          - package.json#scripts.generate:agents-diagram
      - id: build.generate-agent-docs
        name: Generate agent docs
        command: pnpm generate:agent-docs
        type: pnpm
        runs: node scripts/generate-agent-docs.js
        description: Materializes agent documentation files.
        source:
          - package.json#scripts.generate:agent-docs
      - id: build.trikaya-dashboard
        name: Trikāya dashboard
        command: pnpm trikaya:dashboard
        type: pnpm
        runs: node scripts/generate-trikaya-dashboard.mjs
        description: Generates the Trikāya dashboard artifacts under analysis/.
        source:
          - package.json#scripts.trikaya:dashboard
  - key: runtime
    title: Runtime & Developer Services
    description: Commands for launching dev servers, stacks, and runtime utilities.
    entries:
      - id: runtime.dev
        name: UI dev server
        command: pnpm dev
        type: pnpm
        runs: cross-env UI_DIST=http://localhost:5173 pnpm -F mandala-ui dev
        description: Starts the mandala-ui dev server with UI_DIST override.
        source:
          - package.json#scripts.dev
      - id: runtime.dev-ui
        name: Mandala UI dev
        command: pnpm dev:ui
        type: pnpm
        runs: pnpm -F mandala-ui dev
        description: Runs the UI workspace dev server without overrides.
        source:
          - package.json#scripts.dev:ui
      - id: runtime.dev-services
        name: Service development runner
        command: pnpm dev:services
        type: pnpm
        runs: tsx scripts/dev-server.ts
        description: Launches backend/dev services via the TypeScript dev server orchestrator.
        source:
          - package.json#scripts.dev:services
      - id: runtime.dev-stack
        name: Full dev stack
        command: pnpm dev:stack
        type: pnpm
        runs: node scripts/dev-services.mjs --mode=dev
        description: Starts the dev stack orchestrator, enforces port availability, and
          auto-frees default ports via kill-port (disable with `UM_DEV_SERVICES_AUTOFREE_PORTS=0`
          or skip with `UM_DEV_SERVICES_SKIP_PORT_CHECK=1`).
        source:
          - package.json#scripts.dev:stack
      - id: runtime.dev-ports-free
        name: Free dev stack ports
        command: pnpm dev:ports:free
        type: pnpm
        runs: pnpm dlx kill-port 3001 3002 3003 3004 4020 4021
        description: Frees the default Share/Experiments/RAG/Realtime ports before booting
          the dev stack.
        source:
          - package.json#scripts.dev:ports:free
      - id: runtime.dev-breath
        name: Emergence breath watcher
        command: pnpm dev:breath
        type: pnpm
        runs: node scripts/emergence-breath.mjs
        description: Watches sigils, apps/ui, and scripts to rerun `validate:sigillins`,
          rebuild the Trikāya dashboard, and print coverage metrics.
        source:
          - package.json#scripts.dev:breath
      - id: runtime.ai-dev
        name: AI Responses dev prompt
        command: pnpm -F @unified-mandala/ai dev
        type: pnpm
        runs: pnpm -F @unified-mandala/ai dev
        description: Sends a sample prompt through the @unified-mandala/ai Responses wrapper
          (requires OPENAI_API_KEY).
        source:
          - packages/ai/package.json#scripts.dev
      - id: runtime.ai-nats
        name: AI NATS worker
        command: pnpm -F @unified-mandala/ai nats
        type: pnpm
        runs: pnpm -F @unified-mandala/ai nats
        description: Starts the optional NATS request/reply worker on `ai.request`.
        source:
          - packages/ai/package.json#scripts.nats
      - id: runtime.api-dev
        name: AI HTTP bridge
        command: pnpm -F @unified-mandala/api dev
        type: pnpm
        runs: pnpm -F @unified-mandala/api dev
        description: Launches the Express API exposing `/api/ai/chat` (switch transport
          via AI_TRANSPORT=direct|nats).
        source:
          - apps/api/package.json#scripts.dev
      - id: runtime.start
        name: Start UI & dev
        command: pnpm start
        type: pnpm
        runs: pnpm -s build:ui && pnpm -s dev
        description: Builds the UI then launches the dev server.
        source:
          - package.json#scripts.start
      - id: runtime.start-light
        name: Light static server
        command: pnpm start:light
        type: pnpm
        runs: pnpm -s build:ui && node scripts/light-static-server.mjs
        description: Serves the built UI via the light static Node server.
        source:
          - package.json#scripts.start:light
      - id: runtime.start-services
        name: Production services
        command: pnpm start:services
        type: pnpm
        runs: pnpm -s build && NODE_ENV=production node scripts/dev-services.mjs --mode=prod
        description: Builds the workspace and starts services in production mode.
        source:
          - package.json#scripts.start:services
      - id: runtime.start-all
        name: Start full stack
        command: pnpm start:all
        type: pnpm
        runs: pnpm dev:stack
        description: Convenience alias to boot the full dev stack.
        source:
          - package.json#scripts.start:all
      - id: runtime.dev-voiceos
        name: Voice OS control API
        command: pnpm dev:voiceos
        type: pnpm
        runs: node scripts/run-dist.mjs scripts/voice-os-control-api.ts
        description: Launches the Voice OS control API for voice interaction workflows.
        source:
          - package.json#scripts.dev:voiceos
      - id: runtime.ghost-shell-cluster
        name: Ghost Shell cluster
        command: pnpm ghost-shell:cluster
        type: pnpm
        runs: node scripts/run-dist.mjs services/ghost-shell/cluster.ts
        description: Starts the Ghost Shell clustering process.
        source:
          - package.json#scripts.ghost-shell:cluster
      - id: runtime.ghost-shell-server
        name: Ghost Shell server
        command: pnpm ghost-shell:server
        type: pnpm
        runs: node scripts/run-dist.mjs services/ghost-shell/server.ts
        description: Runs the Ghost Shell server entrypoint.
        source:
          - package.json#scripts.ghost-shell:server
      - id: runtime.generate-ghostshell-nginx
        name: Ghost Shell Nginx config
        command: pnpm generate:ghostshell-nginx
        type: pnpm
        runs: node scripts/run-dist.mjs scripts/generate-ghostshell-nginx.ts
        description: Generates Nginx configuration for Ghost Shell deployments.
        source:
          - package.json#scripts.generate:ghostshell-nginx
      - id: runtime.audit-ui-vr
        name: UI VR audit
        command: pnpm audit:ui-vr
        type: pnpm
        runs: node scripts/run-dist.mjs scripts/ui-vr-audit.ts
        description: Audits UI and VR integration paths via Node runner.
        source:
          - package.json#scripts.audit:ui-vr
  - key: smoke
    title: Smoke & Monitoring
    description: Operational smoke tests and monitoring helpers.
    entries:
      - id: smoke.ui
        name: UI dev smoke
        command: pnpm smoke:ui
        type: pnpm
        runs: node scripts/smoke/ui-dev-smoke.mjs
        description: Performs smoke testing against the UI dev server and respects `UI_DEV_URL`
          without spawning a new Vite instance.
        source:
          - package.json#scripts.smoke:ui
      - id: smoke.dev
        name: Dev server smoke
        command: pnpm smoke:dev
        type: pnpm
        runs: node scripts/smoke/dev-server-smoke.mjs
        description: Checks dev server readiness endpoints.
        source:
          - package.json#scripts.smoke:dev
      - id: smoke.mrv
        name: MRV smoke
        command: pnpm smoke:mrv
        type: pnpm
        runs: node scripts/smoke/mrv-smoke.mjs
        description: Executes MRV smoke validation routine.
        source:
          - package.json#scripts.smoke:mrv
      - id: smoke.light-static
        name: Light static smoke
        command: pnpm smoke:light-static
        type: pnpm
        runs: node scripts/smoke/light-static-smoke.mjs
        description: Validates the light static server responses (Brotli/Gzip).
        source:
          - package.json#scripts.smoke:light-static
      - id: chaos.verify-dns-rebind
        name: Verify-Gate DNS rebind drill
        command: pnpm chaos:verify-dns-rebind
        type: pnpm
        runs: node scripts/chaos/verifygate-dns-rebind.mjs
        description: Executes the Vitest chaos harness that simulates a TTL rebind from a public IP to loopback and asserts the gate blocks the rebound.
        source:
          - package.json#scripts.chaos:verify-dns-rebind
          - scripts/chaos/verifygate-dns-rebind.mjs
      - id: chaos.verify-redirect-loop
        name: Verify-Gate redirect loop drill
        command: pnpm chaos:verify-redirect-loop
        type: pnpm
        runs: node scripts/chaos/verifygate-redirect-loop.mjs
        description: Runs the redirect-loop chaos suite to ensure verify-gate stops excessive hops and private redirect targets.
        source:
          - package.json#scripts.chaos:verify-redirect-loop
          - scripts/chaos/verifygate-redirect-loop.mjs
      - id: smoke.nats-docker-up
        name: Docker JetStream (up)
        command: pnpm nats:docker
        type: pnpm
        runs: node scripts/nats-docker.mjs up
        description: Starts or reuses the JetStream-enabled Docker container (`nats:latest
          -js`) on ports 4222/8222.
        source:
          - package.json#scripts.nats:docker
      - id: smoke.nats-docker-restart
        name: Docker JetStream (restart)
        command: pnpm nats:docker:restart
        type: pnpm
        runs: node scripts/nats-docker.mjs restart
        description: Recreates the JetStream container (helpful after configuration changes).
        source:
          - package.json#scripts.nats:docker:restart
      - id: smoke.nats-docker-down
        name: Docker JetStream (down)
        command: pnpm nats:docker:down
        type: pnpm
        runs: node scripts/nats-docker.mjs down
        description: Stops and removes the local JetStream container.
        source:
          - package.json#scripts.nats:docker:down
      - id: smoke.nats-docker-status
        name: Docker JetStream (status)
        command: pnpm nats:docker:status
        type: pnpm
        runs: node scripts/nats-docker.mjs status
        description: Prints the state of the managed JetStream container.
        source:
          - package.json#scripts.nats:docker:status
      - id: smoke.nats-doctor
        name: NATS JetStream doctor
        command: pnpm nats:doctor
        type: pnpm
        runs: node scripts/nats-doctor.mjs
        description: Checks JetStream readiness with retries, uses `$JS.API.INFO` as fallback,
          and prints troubleshooting hints (missing `-js`, timeout, permissions; expects
          `nats:docker` or equivalent to be up).
        source:
          - package.json#scripts.nats:doctor
          - scripts/nats-doctor.mjs
      - id: smoke.ttfb
        name: TTFB smoke
        command: pnpm smoke:ttfb
        type: pnpm
        runs: pnpm -s build:ui && node scripts/smoke/ttfb-smoke.mjs
        description: Measures time-to-first-byte after building the UI.
        source:
          - package.json#scripts.smoke:ttfb
      - id: smoke.agents
        name: Agents smoke
        command: pnpm smoke:agents
        type: pnpm
        runs: node scripts/smoke/agents-smoke.mjs
        description: Runs smoke tests across agent services.
        source:
          - package.json#scripts.smoke:agents
  - key: agents
    title: Agents & Emergence
    description: Agent orchestration, health checks, and emergence scanning.
    entries:
      - id: agents.run
        name: Run agents
        command: pnpm agents:run
        type: pnpm
        runs: node scripts/run-dist.mjs scripts/agents/runner.ts
        description: Launches the primary agent runner.
        source:
          - package.json#scripts.agents:run
      - id: agents.health
        name: Agents health
        command: pnpm agents:health
        type: pnpm
        runs: node scripts/run-dist.mjs scripts/agents/runner.ts --health-all
        description: Executes health checks across all registered agents.
        source:
          - package.json#scripts.agents:health
      - id: agents.metrics
        name: Agents metrics aggregation
        command: pnpm agents:metrics
        type: pnpm
        runs: node scripts/run-dist.mjs scripts/agents/metrics-aggregate.ts
        description: Aggregates metrics emitted by agents.
        source:
          - package.json#scripts.agents:metrics
      - id: agents.audit-domains
        name: Agents domain audit
        command: pnpm agents:audit:domains
        type: pnpm
        runs: node scripts/run-dist.mjs scripts/agents/domain-audit.ts
        description: Audits domain assignments across agent network.
        source:
          - package.json#scripts.agents:audit:domains
      - id: agents.test-golden
        name: Agents golden tests
        command: pnpm agents:test:golden
        type: pnpm
        runs: node scripts/run-dist.mjs scripts/agents/golden-runner.ts
        description: Runs golden record verification for agents.
        source:
          - package.json#scripts.agents:test:golden
      - id: agents.scan
        name: Agents emergence scan
        command: pnpm agents:scan
        type: pnpm
        runs: node scripts/run-dist.mjs scripts/agents/emergence-scan.ts
        description: Scans agents for emergence signals.
        source:
          - package.json#scripts.agents:scan
      - id: agents.route
        name: Agents router
        command: pnpm agents:route
        type: pnpm
        runs: node scripts/agents/router.mjs
        description: Runs the agents router for message routing scenarios.
        source:
          - package.json#scripts.agents:route
      - id: agents.emergence-scan
        name: Composite emergence scan
        command: pnpm emergence:scan
        type: pnpm
        runs: pnpm sigils:index && pnpm agents:scan
        description: Indexes sigils then performs an agent emergence scan.
        source:
          - package.json#scripts.emergence:scan
  - key: sigils
    title: Sigils, Maps & Mandala
    description: Sigil validation, map generation, and mandala topology helpers.
    entries:
      - id: sigils.lint
        name: Sigils lint
        command: pnpm sigils:lint
        type: pnpm
        runs: node scripts/run-dist.mjs scripts/sigils-validate.ts
        description: Validates sigil definitions via dist runner.
        source:
          - package.json#scripts.sigils:lint
      - id: sigils.scan
        name: Sigils scan
        command: pnpm sigils:scan
        type: pnpm
        runs: node scripts/run-dist.mjs scripts/validate-sigils.ts
        description: Scans sigil manifests for consistency.
        source:
          - package.json#scripts.sigils:scan
      - id: sigils.validate-mini
        name: Validate Mandala explanation
        command: pnpm sigils:validate:mini
        type: pnpm
        runs: node scripts/run-dist.mjs scripts/sigils/mini-sigillin-validator.ts
        description: Validates Mandala explanations for CREP, Trikāya and next-step references;
          supports --input/--text/--json.
        source:
          - package.json#scripts.sigils:validate:mini
          - scripts/sigils/mini-sigillin-validator.ts
      - id: sigils.index
        name: Build sigil index
        command: pnpm sigils:index
        type: pnpm
        runs: node scripts/build-sigillin-index.mjs
        description: Generates the sigil index artifacts.
        source:
          - package.json#scripts.sigils:index
      - id: sigils.find-bad-yaml
        name: Lint YAML manifests
        command: pnpm find-bad-yaml
        type: pnpm
        runs: node scripts/find-bad-yaml.mjs
        description: Lints sigil YAML files via yaml-lint and fast-glob before strict
          indexing.
        source:
          - package.json#scripts.find-bad-yaml
      - id: sigils.index-strict
        name: Strict sigil index
        command: pnpm sigils:index:strict
        type: pnpm
        runs: pnpm find-bad-yaml && pnpm sigils:scan && pnpm stac:validate && pnpm sigils:index
        description: Runs strict sigil validation pipeline prior to indexing.
        source:
          - package.json#scripts.sigils:index:strict
      - id: sigils.errors
        name: Inspect sigil errors
        command: pnpm sigils:errors
        type: pnpm
        runs: cat out/sigils_errors.json || echo 'no errors file'
        description: Prints the last sigil error report if available.
        source:
          - package.json#scripts.sigils:errors
      - id: sigils.sigillins-scaffold
        name: Scaffold inter-AI bridges
        command: pnpm sigillins:scaffold
        type: pnpm
        runs: node scripts/scaffold-interai-bridges.mjs
        description: Creates scaffold files for inter-AI sigillin bridges.
        source:
          - package.json#scripts.sigillins:scaffold
      - id: sigils.sigillins-authoring
        name: Sigillin authoring CLI
        command: pnpm sigillins:authoring
        type: pnpm
        runs: node scripts/sigillin-authoring.mjs
        description: Interactive authoring CLI for sigillin records.
        source:
          - package.json#scripts.sigillins:authoring
      - id: sigils.sigillins-build
        name: Build sigillin archive
        command: pnpm sigillins:build
        type: pnpm
        runs: node scripts/build-sigillin-archive.mjs
        description: Constructs sigillin archive bundles.
        source:
          - package.json#scripts.sigillins:build
      - id: sigils.validate-sigillins
        name: Validate sigillins
        command: pnpm validate:sigillins
        type: pnpm
        runs: node scripts/validate-sigillins.mjs
        description: Runs the sigillin validator with schema and semantic checks.
        source:
          - package.json#scripts.validate:sigillins
      - id: sigils.validate-sigillins-changed
        name: Validate staged sigillins
        command: pnpm validate:sigillins:changed
        type: pnpm
        runs: node scripts/sigillins-validate-changed.mjs
        description: Validates only staged Sigillin bridge files (Git hook friendly).
        source:
          - package.json#scripts.validate:sigillins:changed
      - id: sigils.sigillins-report
        name: Generate sigillin reports
        command: pnpm sigillins:report
        type: pnpm
        runs: node scripts/sigillins-generate-reports.mjs
        description: 'Produces JUnit XML and Markdown summaries for governance review
          (default output: out/policy/sigillins/).'
        source:
          - package.json#scripts.sigillins:report
      - id: sigils.map-mandala
        name: Validate Mandala map
        command: pnpm map:mandala
        type: pnpm
        runs: node scripts/mandala-map-validate.mjs
        description: Validates Mandala map artifacts prior to publication.
        source:
          - package.json#scripts.map:mandala
      - id: sigils.maps-build
        name: Build repository map
        command: pnpm maps:build
        type: pnpm
        runs: node scripts/run-dist.mjs scripts/repo-map.ts
        description: Regenerates repository map datasets.
        source:
          - package.json#scripts.maps:build
      - id: sigils.maps-validate
        name: Validate repository maps
        command: pnpm maps:validate
        type: pnpm
        runs: node scripts/maps/validate-maps.mjs
        description: Validates map artifacts (`RepoMap.yaml` braucht `repo`, `ProgramFlow.yaml`
          `meta`).
        source:
          - package.json#scripts.maps:validate
      - id: sigils.maps-list
        name: List mapped files
        command: pnpm maps:list
        type: pnpm
        runs: node -e "console.log(require('./analysis/repo-map.json').length+' files')"
        description: Prints the repository map file count.
        source:
          - package.json#scripts.maps:list
      - id: sigils.graph-build
        name: Build sigillin graph
        command: pnpm graph:build
        type: pnpm
        runs: node scripts/build-sigillin-graph.mjs
        description: Generates graph representations of sigillin relationships.
        source:
          - package.json#scripts.graph:build
  - key: data
    title: Data, Adapters & Ingestion
    description: Dataset builders, adapter workflows, and resonance tooling.
    entries:
      - id: data.adapter-era5
        name: Build ERA5 adapter
        command: pnpm adapter:build:era5
        type: pnpm
        runs: node scripts/adapter-build-era5.mjs
        description: Builds ERA5 fixtures via the Python helper with `.venv` auto-detection
          and runs the post-processor.
        source:
          - package.json#scripts.adapter:build:era5
      - id: data.adapter-oisst
        name: Build OISST adapter
        command: pnpm adapter:build:oisst
        type: pnpm
        runs: node scripts/build-adapter-oisst.mjs
        description: Generates OISST adapter data bundles.
        source:
          - package.json#scripts.adapter:build:oisst
      - id: data.adapter-effis
        name: Build EFFIS adapter
        command: pnpm adapter:build:effis
        type: pnpm
        runs: node scripts/build-adapter-effis.mjs
        description: Builds EFFIS adapter outputs.
        source:
          - package.json#scripts.adapter:build:effis
      - id: data.adapters-ci-install
        name: Install adapter Python deps
        command: pnpm adapters:ci:install
        type: pnpm
        runs: pip install -r src/adapters/requirements.txt
        description: Installs Python requirements for adapters in CI.
        source:
          - package.json#scripts.adapters:ci:install
      - id: data.resonance-calc
        name: Resonance calculation
        command: pnpm resonance:calc
        type: pnpm
        runs: node scripts/run-dist.mjs scripts/resonance-calc.ts
        description: Runs the resonance calculator for sigillin analytics.
        source:
          - package.json#scripts.resonance:calc
      - id: data.scan-ingest
        name: Ingest external scan
        command: pnpm scan:ingest
        type: pnpm
        runs: node scripts/ingest-external-scan.mjs
        description: Scans and ingests external dataset manifests.
        source:
          - package.json#scripts.scan:ingest
      - id: data.stac-validate
        name: Validate STAC
        command: pnpm stac:validate
        type: pnpm
        runs: node scripts/validate-stac.mjs
        description: Validates STAC catalog outputs.
        source:
          - package.json#scripts.stac:validate
      - id: data.stac-validate-item
        name: Validate STAC item
        command: pnpm stac:validate:item
        type: pnpm
        runs: node scripts/run-dist.mjs scripts/validate-stac.ts out/example.item.json
        description: Validates a single STAC item artifact.
        source:
          - package.json#scripts.stac:validate:item
  - key: observability
    title: Observability & Monitoring
    description: Prometheus/Grafana smoke checks and monitoring utilities.
    entries:
      - id: observability.check
        name: Verify Prometheus/Grafana stack
        command: pnpm observability:check
        type: pnpm
        runs: node scripts/run-dist.mjs scripts/observability/prometheus-target-check.ts
        description: Verifies Prometheus `/api/v1/targets` and Grafana `/api/health` (Port
          3300); `PROMETHEUS_REQUIRE_ACTIVE=0` erlaubt leere Targets, `OBSERVABILITY_SKIP_GRAFANA=1`
          überspringt den Grafana-Teil.
        source:
          - package.json#scripts.observability:check
          - scripts/observability/prometheus-target-check.ts
  - key: tasks
    title: Conversations & Task Automation
    description: Conversation parsing, to-do curation, and fractal task orchestration.
    entries:
      - id: tasks.split-conversations
        name: Split conversations
        command: pnpm split:conversations
        type: pnpm
        runs: node scripts/split-conversations.js
        description: Splits long conversation logs into manageable segments.
        source:
          - package.json#scripts.split:conversations
      - id: tasks.analyze-conversations
        name: Analyze conversations
        command: pnpm analyze:conversations
        type: pnpm
        runs: node scripts/analyze-conversations.js
        description: Runs analytics over conversation datasets.
        source:
          - package.json#scripts.analyze:conversations
      - id: tasks.grep-conversations
        name: Grep conversations
        command: pnpm grep:conversations
        type: pnpm
        runs: node scripts/filter-conversations.js
        description: Filters conversations by pattern.
        source:
          - package.json#scripts.grep:conversations
      - id: tasks.parse-newconversations
        name: Parse new advanced conversations
        command: pnpm parse:newconversations
        type: pnpm
        runs: node scripts/parse-newadvanced-conversations.js
        description: Parses new advanced conversation exports into structured data.
        source:
          - package.json#scripts.parse:newconversations
      - id: tasks.conversations-grep-dist
        name: Run dist conversation parser
        command: pnpm conversations:grep
        type: pnpm
        runs: node scripts/run-dist.mjs scripts/parse-newadvancedconversations.ts
        description: Executes the TypeScript conversation parser via dist runner.
        source:
          - package.json#scripts.conversations:grep
      - id: tasks.update-advanced-todo
        name: Update advanced to-do
        command: pnpm update:advanced-todo
        type: pnpm
        runs: node scripts/update-advanced-todo.js
        description: Refreshes the advanced to-do manifest.
        source:
          - package.json#scripts.update:advanced-todo
      - id: tasks.update-code-todos
        name: Update code TODOs
        command: pnpm update:code-todos
        type: pnpm
        runs: node scripts/update-code-todos.cjs
        description: Extracts and updates in-code TODO references.
        source:
          - package.json#scripts.update:code-todos
      - id: tasks.update-newadvanced-todo
        name: Update new advanced to-do
        command: pnpm update:newadvanced-todo
        type: pnpm
        runs: node scripts/update-newadvanced-todo.js
        description: Updates the new advanced to-do dataset.
        source:
          - package.json#scripts.update:newadvanced-todo
      - id: tasks.update-fractal-todo
        name: Update fractal to-do
        command: pnpm update:fractal-todo
        type: pnpm
        runs: node scripts/update-fractal-todo.js
        description: Refreshes fractal to-do manifests.
        source:
          - package.json#scripts.update:fractal-todo
      - id: tasks.update-advanced-progress
        name: Update advanced progress
        command: pnpm update:advanced-progress
        type: pnpm
        runs: node repositorypflege/update-advanced-progress.js
        description: Regenerates advanced progress summary.
        source:
          - package.json#scripts.update:advanced-progress
      - id: tasks.update-todo-sigil
        name: Update todo sigil
        command: pnpm update:todo-sigil
        type: pnpm
        runs: node scripts/update-todo-sigil.js
        description: Syncs sigil references in todo manifests.
        source:
          - package.json#scripts.update:todo-sigil
      - id: tasks.validate-todos
        name: Validate implicit todos
        command: pnpm validate:todos
        type: pnpm
        runs: node scripts/validate-implicit-todos.js
        description: Validates implicit TODO extraction results.
        source:
          - package.json#scripts.validate:todos
      - id: tasks.validate-advancedtodo
        name: Validate advanced todo
        command: pnpm validate:advancedtodo
        type: pnpm
        runs: node scripts/validate-advancedtodo.js
        description: Checks the advanced to-do manifest for consistency.
        source:
          - package.json#scripts.validate:advancedtodo
      - id: tasks.generate-initial-tasks
        name: Generate initial tasks
        command: pnpm generate:initial-tasks
        type: pnpm
        runs: node repositorypflege/generate-initial-tasks.js
        description: Seeds task manifests from repository state.
        source:
          - package.json#scripts.generate:initial-tasks
      - id: tasks.fraktalrun-import
        name: Fraktalrun import
        command: pnpm fraktalrun:import
        type: pnpm
        runs: node scripts/run-dist.mjs scripts/fraktalrun-import.ts
        description: Imports fractal run data into the repository manifests.
        source:
          - package.json#scripts.fraktalrun:import
  - key: policy
    title: Governance & Policy
    description: Policy validation and CI governance gates.
    entries:
      - id: policy.policy-check
        name: Policy suite
        command: pnpm policy:check
        type: pnpm
        runs: node scripts/policy-suite.mjs
        description: Runs the unified policy suite (OPA, Guardrails, Kyverno) and persists
          sigillin governance reports to out/policy/sigillins/.
        source:
          - package.json#scripts.policy:check
      - id: policy.opa-test
        name: OPA policy tests
        command: pnpm opa:test
        type: pnpm
        runs: node scripts/opa/run-opa-test.mjs
        description: Runs `opa test` for `apps/ethics-api/opa`, honours `OPA_BIN` or ./bin/opa and forwards extra CLI flags.
        source:
          - package.json#scripts.opa:test
      - id: policy.opa-bundle
        name: OPA bundle build
        command: pnpm opa:bundle
        type: pnpm
        runs: node scripts/opa/build-opa-bundle.mjs
        description: Builds the Mandala ethics OPA bundle (`dist/opa/mandala-ethics-bundle.tar.gz`) and writes revision metadata.
        source:
          - package.json#scripts.opa:bundle
          - scripts/opa/build-opa-bundle.mjs
      - id: policy.opa-sign
        name: OPA bundle sign
        command: pnpm opa:sign
        type: pnpm
        runs: node scripts/opa/sign-opa-bundle.mjs
        description: Computes the bundle SHA256 fingerprint and optionally GPG-signs it (`OPA_SIGN_ENABLE=1`).
        source:
          - package.json#scripts.opa:sign
          - scripts/opa/sign-opa-bundle.mjs
      - id: policy.opa-verify
        name: OPA bundle verify
        command: pnpm opa:verify
        type: pnpm
        runs: node scripts/opa/verify-opa-bundle.mjs
        description: Verifies SHA256/GPG signatures and performs a smoke `opa eval` against the bundle.
        source:
          - package.json#scripts.opa:verify
          - scripts/opa/verify-opa-bundle.mjs
      - id: policy.opa-bundle-sign
        name: OPA bundle build+sign
        command: pnpm opa:bundle:sign
        type: pnpm
        runs: pnpm opa:bundle && pnpm opa:sign && pnpm opa:verify
        description: Convenience wrapper to build, sign, and verify the ethics bundle in one step (CI artefact path `dist/opa/`).
        source:
          - package.json#scripts.opa:bundle:sign
      - id: policy.kyverno-validate
        name: Kyverno dry run
        command: pnpm kyverno:validate
        type: pnpm
        runs: node tools/kyverno-dry-run.mjs
        description: Executes Kyverno validation across manifests.
        source:
          - package.json#scripts.kyverno:validate
      - id: policy.ci-sigils
        name: CI sigils gate
        command: pnpm ci:sigils
        type: pnpm
        runs: pnpm sigils:index:strict && pnpm test:sigil tests/fixtures/sigillin/good.yaml
          && pnpm resonance:calc
        description: CI pipeline for sigils combining strict index, CLI tests, and resonance
          calc.
        source:
          - package.json#scripts.ci:sigils
      - id: policy.ci-adapters-offline
        name: Adapters offline build
        command: pnpm ci:adapters-offline
        type: pnpm
        runs:
          cross-env CI=true pnpm adapter:build:oisst && cross-env CI=true pnpm adapter:build:era5
          || true
        description: Runs offline adapter builds in CI with non-blocking fallback (cross-platform
          env export).
        source:
          - package.json#scripts.ci:adapters-offline
  - key: aeon
    title: Aeon & Symbolic Operations
    description: Aeon transitions, memory persistence, and symbolic rituals.
    entries:
      - id: aeon.aeon-transition
        name: Aeon transition workflow
        command: pnpm aeon:transition
        type: pnpm
        runs: node scripts/aeon-transition-workflow.js
        description: Handles Aeon transition orchestration tasks.
        source:
          - package.json#scripts.aeon:transition
      - id: aeon.symbolzeit
        name: Symbolzeit run
        command: pnpm symbolzeit:run
        type: pnpm
        runs: node scripts/symbolzeit-runner.js
        description: Executes the Symbolzeit ritual workflow.
        source:
          - package.json#scripts.symbolzeit:run
      - id: aeon.export-depth-bundle
        name: Depth bundle export
        command: pnpm export_depth_bundle
        type: pnpm
        runs: node scripts/run-dist.mjs scripts/export-depth-bundle.ts
        description: Exports depth bundle artifacts referenced by sigillin governance.
        source:
          - package.json#scripts.export_depth_bundle
      - id: aeon.store-commit-memory
        name: Commit memory store
        command: pnpm store:commit-memory
        type: pnpm
        runs: node GenesisAeonZIPMEM/commitMemory/commit-memory.js
        description: Persists Genesis Aeon ZIP memory state as part of symbolic continuity.
        source:
          - package.json#scripts.store:commit-memory
      - id: aeon.generate-next-sigil
        name: Generate next sigil
        command: pnpm generate:next-sigil
        type: pnpm
        runs: node scripts/generate-next-sigil.js
        description: Derives the next sigil entry for symbolic governance.
        source:
          - package.json#scripts.generate:next-sigil
  - key: prompts
    title: Prompts & Coaching
    description: Prompt management and coaching utilities.
    entries:
      - id: prompts.coach
        name: Prompt coach runner
        command: pnpm prompts:coach
        type: pnpm
        runs: node scripts/run-dist.mjs scripts/prompt-coach.ts
        description: Dist-first prompt coach execution; pass `--dry` to preview suggestions
          without writing files.
        source:
          - package.json#scripts.prompts:coach
tools:
  - id: tool.run-dist
    name: Dist-first runner
    location: scripts/run-dist.mjs
    usage: node scripts/run-dist.mjs <entry.ts>
    description: Executes TypeScript entrypoints via compiled dist artifacts ensuring
      production parity.
  - id: tool.light-static-server
    name: Light static server
    location: scripts/light-static-server.mjs
    usage: node scripts/light-static-server.mjs
    description: Serves built UI assets with Brotli/Gzip checks and health endpoints.
  - id: tool.policy-suite
    name: Policy suite orchestrator
    location: scripts/policy-suite.mjs
    usage: node scripts/policy-suite.mjs
    description: Aggregates OPA, Guardrails, and Kyverno validation routines.
  - id: tool.kyverno-dry-run
    name: Kyverno dry-run helper
    location: tools/kyverno-dry-run.mjs
    usage: node tools/kyverno-dry-run.mjs
    description: Runs Kyverno CLI simulations for policy enforcement.
  - id: tool.dev-services
    name: Dev services orchestrator
    location: scripts/dev-services.mjs
    usage: node scripts/dev-services.mjs --mode=<dev|prod>
    description: Controls composite dev/prod service stacks for runtime parity.
  - id: tool.dev-server
    name: Dev server TypeScript entry
    location: scripts/dev-server.ts
    usage: tsx scripts/dev-server.ts
    description: Starts TypeScript-based dev services via tsx runtime.
  - id: tool.qa-runner
    name: QA test runner
    location: scripts/qa-test-runner.ts
    usage: node scripts/run-dist.mjs scripts/qa-test-runner.ts [config]
    description: Runs QA regression scenarios defined in JSON manifests.
  - id: tool.smoke-suite
    name: Smoke test suite
    location: scripts/smoke/
    usage: node scripts/smoke/<name>.mjs
    description: Collection of smoke test entrypoints for UI, dev, MRV, agents, and
      static flows.
  - id: tool.adapter-postprocess
    name: Adapter post-process
    location: scripts/adapter-postprocess.mjs
    usage: node scripts/adapter-postprocess.mjs <adapter>
    description: Normalizes adapter outputs after Python generation steps.
  - id: tool.fraktalrun-import
    name: Fraktalrun importer
    location: scripts/fraktalrun-import.ts
    usage: node scripts/run-dist.mjs scripts/fraktalrun-import.ts
    description: Imports fractal run fragments into codex manifests.
scripts:
  - id: script.setup-dev-env
    path: scripts/setup-dev-env.sh
    description: Bash bootstrap script for Linux/macOS developer workstations.
  - id: script.setup-dev-env-windows
    path: scripts/setup-dev-env.ps1
    description: PowerShell bootstrap script for Windows developer workstations; skips
      corepack enable without admin rights, recognises Docker-managed NATS container
      status (inkl. Start-Hinweise) und hält NATS-Installationsbefehle bereit.
  - id: script.run-powershell
    path: scripts/run-powershell.mjs
    description: Node helper selecting pwsh or Windows PowerShell before invoking repository
      PowerShell tooling.
  - id: script.build_pr_e_tree
    path: build_pr_E_tree.sh
    description: Helper script for building PR tree visualizations (variant E).
  - id: script.build_pr_f_tree
    path: build_pr_F_tree.sh
    description: Helper script for building PR tree visualizations (variant F).
  - id: script.build_pr_g_tree
    path: build_pr_G_tree.sh
    description: Helper script for building PR tree visualizations (variant G).
  - id: script.codex-sync
    path: codex-sync.sh
    description: Synchronizes codex states across environments.
  - id: script.docker-compose-local
    path: docker-compose.local.yaml
    description: Docker Compose definition for local offline stack parity.
  - id: script.docker-compose
    path: docker-compose.yml
    description: Primary Docker Compose file with multiple service profiles.
  - id: script.setup-dev-container
    path: Dockerfile.dev
    description: Dev container definition aligning Node 20 + Python 3 toolchains.
  - key: maintenance
    title: Maintenance & Automation
    description: Housekeeping commands and repository maintenance tasks.
    entries:
      - id: maintenance.backlog-consolidate
        name: Backlog consolidate
        command: pnpm backlog:consolidate
        type: pnpm
        runs: node scripts/meta/backlog-consolidate.mjs
        description: Scans advancedToDo_parts and writes `out/backlog/fragment-index.json`; updates `advancedprogress.json.backlogIndex`.
        source:
          - scripts/meta/backlog-consolidate.mjs
          - .github/workflows/backlog-consolidate.yml