AI Bootstrap and Authority

Canonical source: .ai/BOOTSTRAP.md — this page is rendered from it on every publish; edit the source.

ClawAI — Agent Bootstrap

You are working in ClawAI — "Every AI, one workspace" (product positioning: docs/01-executive-context/product-vision.md). Architecturally, a local-first AI orchestration platform: 21 NestJS microservices + a Next.js frontend + 6 shared packages, in an npm-workspace monorepo. Events flow over RabbitMQ (topic exchange claw.events); nginx reverse-proxies /api/v1/* to services.

First task protocol (do this before touching code)

1. Run: npm run knowledge:context -- --task="<what you are doing>"
2. Read: .ai/local/current-context.md — it lists the affected workspaces, governing rules, matching skills, files to inspect, tests, and pitfalls.
3. Follow the rules it cites. Do not invent repository facts — derive them from the manifests in .ai/manifests/ and the real code.

Canonical authority (higher wins on conflict)

1. CLAUDE.md — long-form operating policy
2. rules/00-non-negotiable-rules.md — engineering blockers
3. context/architecture-map.md — structural architecture
4. context/stack-and-toolchain.md — commands + toolchain
5. Numbered rules/* → skills/* → context/* + memory/*
6. Generated .ai/ manifests
7. Compact AI-family routers (AGENTS.md, CODEX.md, cursor.md, …)

Absolute prohibitions (blockers — never do these)

• NEVER --no-verify or otherwise bypass git hooks.
• NEVER suppress lint/type errors (eslint-disable, @ts-ignore, any, as unknown as).
• NEVER cross a service's database boundary — use HTTP or RabbitMQ.
• NEVER put business logic in controllers or DB calls outside repositories.
• NEVER log secrets/tokens/passwords; NEVER expose secrets to the frontend.
• NEVER add user-facing text without i18n in all 13 locales.
• NEVER add code without a test.

Landing a change (rules/23)

npm run affected:list                 # what your diff touches + why
git add <explicit paths> && git commit  # pre-commit gates the staged change; Docs: trailer (rules/63)
git push                              # pre-push gates every pushed ref; then CI

The hooks run the gates the change type needs; run nothing else by hand. Full validation before release: npm run release:preflight.

Where things live

• Architecture map → context/architecture-map.md
• Service catalog → context/service-catalog.md (generated: .ai/manifests/services.json)
• Rules → rules/ · Skills → skills/ · Reviewer roles → agents/
• Durable pitfalls/lessons → memory/
• Task packs → .ai/packs/

Fast facts (generated)

• Services (21): agent-service :4015, audit-service :4007, auth-service :4001, chat-service :4002, connector-service :4003, file-generation-service :4013, file-service :4006, health-service :4009, image-service :4012, llamacpp-service :4017, memory-service :4005, ollama-service :4008, payment-service :4018, plugin-service :4021, research-service :4016, routing-service :4004, thread-generation-service :4020, threads-service :4019, workspace-service :4014
• Shared packages: @claw/shared-auth, @claw/shared-constants, @claw/shared-entitlements, @claw/shared-rabbitmq, @claw/shared-types, @claw/shared-utilities
• Events: 190 on claw.events
• Permissions: 94 · Env vars: 386
• API endpoints: 973 · Frontend pages: 184

This file is generated. To change it, edit the renderer + policy sources and run npm run knowledge:build.