siclaw: Instructions file for Claude Code

Siclaw — Operating Manual for Claude

Auto-loaded at session start. Keep concise — deep reference lives in docs/design/.

---

What This Project Is

Siclaw is an AI-powered SRE copilot that runs Kubernetes diagnostics via natural language.

Three runtime modes share one agent core:

Headless CLI (single diagnostic invocation; optionally paired with local Portal — see invariants.md §1.4)
Gateway + LocalSpawner (multi-user, local dev — all users share one process + filesystem)
Gateway + K8sSpawner  (production — one isolated pod per user)

---

Critical Architecture Invariants

Full spec: docs/design/invariants.md

🔴 Local Mode: Shared Filesystem

LocalSpawner runs ALL AgentBox instances in-process, sharing one filesystem.

• skillsHandler.materialize() must NOT be called in local mode — wipes all users' skills
• Local skills sync writes only to skills/user/{userId}/ scoped paths

🔴 Skill Bundle Contract

buildSkillBundle() packages only global + skillset (dev only) + personal skills selected for the current workspace. Core skills are baked into the Docker image. materialize() does NOT restore core skills.

🔴 Headless CLI + Local Portal: Read-Only Snapshot Contract

When siclaw --prompt "..." starts in a cwd that has a reachable local Portal (.siclaw/local-secrets.json present AND /api/health responds), Portal becomes the read-only source of truth for skills, knowledge, credentials, agents, MCP servers, and LLM providers. Do not add code paths that let the headless CLI write back to Portal — writes belong in Portal Web UI.

• Snapshot contract: GET /api/v1/cli-snapshot?agent=<name> — see src/portal/cli-snapshot-api.ts. Agent-scoped joins via agent_skills, agent_hosts, agent_clusters, agent_mcp_servers, agent_knowledge_repos.
• Materialization: payload unpacked to .siclaw/.portal-snapshot/run-<random>/{skills,knowledge,credentials}/. Each invocation owns its root and removes only that root on exit or cancellation. Empty snapshots remain authoritative; never substitute ambient resources. These materializers (src/lib/portal-*-materializer.ts) are NOT the same as skillsHandler.materialize() (§1.2) — different code path, scoped ephemeral output, safe in headless CLI cwd.
• CLI requires --prompt and exits on missing provider configuration. Interactive setup and terminal slash commands have been removed; configuration belongs in Portal Web UI or a pre-provisioned standalone settings file.
• Standalone headless CLI (no Portal, no selected agent): legacy settings.json flow unchanged. A selected Portal agent must load successfully; never silently execute against local configuration when its snapshot fails.