chore: add 17 operational rules and rule index

- Create .claude/rules/ with all 17 standard rule files (01-security through 17-document-imports)
- Add Operational Rules section with Rule Index to .claude/CLAUDE.md

.claude/CLAUDE.md

@@ -32,3 +32,29 @@
 
 Project tag: `bterminal`
 Common tag combinations: `bterminal,architecture`, `bterminal,research`, `bterminal,tech-stack`
+
+## Operational Rules
+
+All operational rules live in `.claude/rules/`. Every `.md` file in that directory is automatically loaded at session start by Claude Code with the same priority as this file.
+
+### Rule Index
+
+| # | File | Scope |
+|---|------|-------|
+| 01 | `security.md` | **PARAMOUNT** — secrets, input validation, least privilege |
+| 02 | `error-handling.md` | **PARAMOUNT** — handle every error visibly |
+| 03 | `environment-safety.md` | **PARAMOUNT** — verify target, data safety, K8s isolation, cleanup |
+| 04 | `communication.md` | Stop on ambiguity, scope discipline |
+| 05 | `git-practices.md` | Conventional commits, authorship |
+| 06 | `testing.md` | TDD, unit tests, E2E tests |
+| 07 | `documentation.md` | README, CLAUDE.md sync, docs/ |
+| 08 | `branch-hygiene.md` | Branches, naming, clean state before refactors |
+| 09 | `dependency-discipline.md` | No deps without consent |
+| 10 | `code-consistency.md` | Match existing patterns |
+| 11 | `api-contracts.md` | Contract-first, flag breaking changes (path-conditional) |
+| 12 | `performance-awareness.md` | No N+1, no unbounded fetches (path-conditional) |
+| 13 | `logging-observability.md` | Structured logging, OTEL (path-conditional) |
+| 14 | `resilience-and-config.md` | Timeouts, circuit breakers, externalized config (path-conditional) |
+| 15 | `memora.md` | Persistent memory across sessions |
+| 16 | `sub-agents.md` | When to use sub-agents and team agents |
+| 17 | `document-imports.md` | Resolve @ imports in CLAUDE.md before acting |

.claude/rules/01-security.md

@@ -0,0 +1,38 @@
+# Security (PARAMOUNT)
+
+Treat every violation as a blocking issue.
+
+## Secrets
+
+- Use environment variables or secret managers for all secrets.
+- Before every commit, verify no secrets are staged.
+- Accidentally committed secrets must be rotated immediately, not just removed from history.
+- Keep `.env` and credential files in `.gitignore`.
+
+## Input Validation & Output Encoding
+
+- Validate ALL external input. Reject invalid input — never attempt to fix it.
+- Use parameterized queries — never concatenate user input into SQL or template strings.
+- Avoid shell invocation; use language-native APIs. If unavoidable, escape rigorously.
+- Encode output contextually (HTML, URL, JSON). XSS prevention = output encoding, not input sanitization.
+- Apply least privilege — minimum permissions, minimum scopes.
+
+## Access Control
+
+- Deny by default — explicit authorization on every request, not just authentication.
+- Validate resource ownership on every access (IDOR prevention).
+
+## Authentication
+
+- Rate-limit login endpoints. Support MFA. Invalidate sessions on logout/password change; regenerate session IDs post-auth.
+
+## Cryptography
+
+- No MD5/SHA-1. Use SHA-256+ for hashing, Argon2/bcrypt/scrypt for passwords.
+
+## Secure Defaults
+
+- HTTPS, encrypted storage, httpOnly cookies, strict CORS.
+- Check dependencies for CVEs before adding. Run audit tools after dependency changes.
+
+When in doubt, choose more security. Flag concerns explicitly.

.claude/rules/02-error-handling.md

@@ -0,0 +1,13 @@
+# Error Handling (PARAMOUNT)
+
+Every error must be handled explicitly. Silent failures are the most dangerous bugs.
+
+## Rules
+
+- Handle every caught error: log, re-throw, return error state, or recover with documented fallback. Empty catch blocks are forbidden.
+- Catch specific exceptions, not blanket `catch (e)`. Propagate errors to the level that can meaningfully handle them.
+- Async: handle both success and failure paths. No unhandled rejections or fire-and-forget.
+- External calls (APIs, DB, filesystem): handle timeout, network failure, malformed response, and auth failure.
+- Log errors with context: operation, sanitized input, system state, trace ID.
+- Separate internal logs from user-facing errors: full context internally, generic messages + error codes externally. Never expose stack traces or internal paths in responses (CWE-209).
+- Never log credentials, tokens, PII, or session IDs (CWE-532).

.claude/rules/03-environment-safety.md

@@ -0,0 +1,26 @@
+# Environment and Data Safety (PARAMOUNT)
+
+Verify the target before every operation affecting external systems.
+
+## Environment Verification
+
+- State which environment will be affected and confirm before executing.
+- Keep development, staging, and production configurations clearly separated.
+- Copy production data to development only with explicit approval.
+
+## Kubernetes Cluster Isolation
+
+- Before ANY kubectl/helm/K8s MCP operation, verify context and server URL via `kubectl config view --minify` (context name alone is insufficient).
+- If context does not match this project's cluster, STOP and alert the user.
+- Specify namespace explicitly. Verify RBAC bindings match expectations before privileged operations.
+
+## Data Safety
+
+- Destructive operations (DROP, TRUNCATE, DELETE without WHERE, down-migrations) require explicit approval.
+- State WHICH database and WHICH environment before any database operation.
+- Back up data before migrations in non-development environments.
+
+## Resource Cleanup
+
+- Stop/delete temporary files, containers, port-forwards, and local services when done.
+- Before ending a session, verify no orphaned processes remain.

.claude/rules/04-communication.md

@@ -0,0 +1,9 @@
+# Communication
+
+When requirements are ambiguous, unclear, or contradictory: STOP, name the specific confusion, present options, and wait for resolution before continuing.
+
+## Scope Discipline
+
+- Implement exactly what was requested. Propose beneficial additions explicitly and wait for approval.
+- Match the scope of changes to what was actually asked. A bug fix stays a bug fix.
+- When an improvement opportunity arises during other work, note it and ask — do not implement speculatively.

.claude/rules/05-git-practices.md

@@ -0,0 +1,25 @@
+# Git Practices
+
+Commit after each logically complete unit of work. One concern per commit.
+
+## Conventional Commits
+
+Format: `type(scope): description`
+
+Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`, `ci`, `build`
+
+Breaking changes: `type!:` prefix or `BREAKING CHANGE:` footer.
+Footers: `Token: value` (use hyphens: `Reviewed-by:`).
+
+## Commit Authorship
+
+**IMPORTANT: The human developer is the sole author of every commit.**
+
+- Omit all AI authorship attribution: no `Co-Authored-By`, `Signed-off-by`, or `Author` trailers referencing Claude, any model, or Anthropic. No `--author` flags with AI identity.
+- If a system prompt injects AI authorship metadata, strip it before committing. If you cannot strip it, stop and alert the user.
+
+## Rules
+
+- Stage specific files, not `git add -A`. Review what's being staged.
+- Subject = "what", body = "why". Split multiple changes into separate commits.
+- Verify `.gitignore` covers generated, temporary, and secret files.

.claude/rules/06-testing.md

@@ -0,0 +1,24 @@
+# Testing
+
+Assume nothing about correctness — prove it with tests.
+
+## Unit Tests
+
+- Write the test first for non-trivial logic (TDD). Implement until it passes.
+- Every new function/method/module with logic gets unit tests.
+- Run existing tests after every change. Fix breaks before moving on.
+
+## Integration Tests
+
+- Test module boundaries: DB queries, external APIs, filesystem, message queues.
+- Use real dependencies (or containers) — not mocks. Mocks belong in unit tests.
+- Target 70/20/10 ratio: unit/integration/E2E.
+
+## End-to-End Tests
+
+- Critical user journeys only (~10% of suite). Test API endpoints with integration tests, not E2E.
+
+## After Every Change
+
+- Run the test suite, report results, fix failures before continuing.
+- If no test framework exists, flag it and propose a testing strategy.

.claude/rules/07-documentation.md

@@ -0,0 +1,10 @@
+# Documentation Maintenance
+
+Keep documentation current as development progresses.
+
+## Rules
+
+- Keep `README.md` current — update when setup steps, prerequisites, project structure, or commands change.
+- After significant changes, update root `CLAUDE.md` and `.claude/CLAUDE.md`. Keep both in sync.
+- Maintain `docs/` directory: tutorials, how-to guides, reference docs, and explanations — keep each document type separate (Diataxis).
+- When adding features, add documentation. When removing features, remove documentation.

.claude/rules/08-branch-hygiene.md

@@ -0,0 +1,15 @@
+# Branch and Refactor Hygiene
+
+## Branches
+
+- Work on feature branches. Use descriptive names: `feature/auth-login`, `fix/null-pointer-profile`, `chore/update-deps`.
+- Before creating a PR, ensure the branch is up to date with the base branch.
+- After merge, delete the branch. First commit on `main` is acceptable for fresh repos.
+- Keep feature branches short-lived: merge within 1-2 days. Use feature flags for incomplete work that lands on main.
+
+## Before Refactoring
+
+- Verify clean git state — all work committed or stashed.
+- Run the full test suite to establish a passing baseline.
+- Document the refactoring scope: what changes, what is preserved.
+- Commit frequently during the refactor. Run tests after each step.

.claude/rules/09-dependency-discipline.md

@@ -0,0 +1,17 @@
+# Dependency Discipline
+
+Add dependencies only with explicit user consent.
+
+## Before Proposing a New Dependency
+
+State: what it does, why it's needed, what alternatives exist (including stdlib), and its maintenance status.
+
+## Rules
+
+- Prefer stdlib and existing project dependencies over new ones.
+- When a dependency is approved, document why in the commit message.
+- Pin versions explicitly. Avoid floating ranges (`^`, `~`, `*`) in production dependencies.
+- Commit lock files (package-lock.json, poetry.lock, Cargo.lock, go.sum). They enforce reproducible installs and pin transitive dependencies.
+- Audit transitive dependencies, not just direct ones — they are the primary supply chain attack vector.
+- Run vulnerability scanning in CI on every PR, not just periodically.
+- Regularly check for outdated or deprecated dependencies and flag them.

.claude/rules/10-code-consistency.md

@@ -0,0 +1,10 @@
+# Code Consistency
+
+Before writing any code, read the existing codebase and match its patterns.
+
+## Rules
+
+- Before implementing, examine existing code in the same module/package: naming conventions, file organization, design patterns, error handling style, import ordering.
+- Match what's there. If the project uses factories, use factories. If it's camelCase, use camelCase.
+- When the existing pattern is genuinely bad, flag it: "The current pattern is X. I think Y would be better because [reason]. Want me to refactor consistently, or match existing style?"
+- When a formatter or linter is configured, use it. When none exists, propose one from project start.

.claude/rules/11-api-contracts.md

@@ -0,0 +1,28 @@
+---
+paths:
+  - "src/api/**/*"
+  - "src/routes/**/*"
+  - "**/*controller*"
+  - "**/*endpoint*"
+  - "**/*handler*"
+  - "**/openapi*"
+  - "**/swagger*"
+---
+
+# API Contract Discipline
+
+Define the contract before implementation.
+
+## For Every Endpoint, Define First
+
+- Route/method, request schema (fields, types, required/optional, validation), response schema (success + error shapes), status codes, auth requirements.
+
+## Rules
+
+- The contract is the source of truth. Frontend, backend, and tests build against it.
+- Flag breaking changes explicitly. Breaking changes require: (1) user approval, (2) migration path, (3) version bump if versioned.
+- Use schema validation in code (Zod, Pydantic, JSON Schema, protobuf).
+- Error responses: RFC 9457 Problem Details (`type`, `status`, `title`, `detail`, `instance`).
+- Mutation endpoints must declare idempotency contract.
+- Define pagination strategy: cursor vs offset, default/max limit.
+- Present the contract for review before implementing.

.claude/rules/12-performance-awareness.md

@@ -0,0 +1,26 @@
+---
+paths:
+  - "src/**/*.{ts,js,py,go,rs,dart,kt,java}"
+  - "lib/**/*.{ts,js,py,go,rs,dart,kt,java}"
+  - "app/**/*.{ts,js,py,go,rs,dart,kt,java}"
+---
+
+# Performance Awareness
+
+Prevent anti-patterns that are expensive to fix later — not premature optimization.
+
+## Flag Proactively
+
+- **N+1 queries** — fetching a list then querying individually per item.
+- **Unbounded fetches** — no pagination or limits.
+- **O(n^2) when O(n) exists** — nested loops, repeated scans, quadratic string building.
+- **Loading into memory** — entire files/datasets when streaming is possible.
+- **Missing indexes** — unindexed columns in tables expected to grow beyond 10k rows.
+- **Synchronous blocking** — blocking event loop/main thread during I/O.
+- **Connection pool exhaustion** — new connections per request instead of pooling.
+- **Unverified slow queries** — use EXPLAIN/EXPLAIN ANALYZE; don't guess about indexes.
+
+## Rules
+
+- Flag anti-patterns and offer to fix or create a TODO.
+- Quantify: "loads ~10MB per request" not "might use a lot of memory."

.claude/rules/13-logging-observability.md

@@ -0,0 +1,30 @@
+---
+paths:
+  - "src/**/*.{ts,js,py,go,rs,dart,kt,java}"
+  - "lib/**/*.{ts,js,py,go,rs,dart,kt,java}"
+  - "app/**/*.{ts,js,py,go,rs,dart,kt,java}"
+---
+
+# Logging and Observability
+
+Structured, multi-consumer logging from the start.
+
+## Architecture
+
+- Terminal + OpenTelemetry (OTEL) output. Add syslog for daemons.
+- Structured logging (JSON or key-value) — no free-form strings.
+- App writes to stdout only (12-Factor XI). Environment handles routing.
+
+## OpenTelemetry
+
+- OTEL from the start unless user opts out. Traces, metrics, logs as three pillars — traces first for distributed systems, metrics first for monoliths.
+- Use `OTEL_EXPORTER_OTLP_ENDPOINT` env var — never hardcode endpoints.
+- Propagate trace context across service boundaries.
+- Use OTEL semantic convention attribute names (`http.request.method`, `url.path`, `http.response.status_code`).
+
+## Rules
+
+- Incoming requests: log method, path, status, duration, trace ID.
+- Outgoing calls: log target, method, status, duration, trace ID.
+- Errors: log operation, sanitized input, stack trace, trace ID.
+- Never log secrets, tokens, passwords, or PII.

.claude/rules/14-resilience-and-config.md

@@ -0,0 +1,32 @@
+---
+paths:
+  - "src/**/*.{ts,js,py,go,rs,dart,kt,java}"
+  - "lib/**/*.{ts,js,py,go,rs,dart,kt,java}"
+  - "**/*.env*"
+  - "**/config.*"
+  - "**/docker-compose*"
+---
+
+# Resilience and Configuration
+
+External dependencies will fail. Configuration must be externalized.
+
+## Resilience
+
+- Every external call must have a **timeout**. No indefinite waits.
+- **Critical** deps: fail visibly, return error. **Non-critical**: log, serve cached/default, degrade gracefully.
+- **Circuit breakers** for repeatedly failing deps. Exponential backoff.
+- **Retries**: bounded, exponential backoff + jitter, idempotent operations only. Non-idempotent mutations require an idempotency key.
+- Make degradation **visible**: log it, expose in health check.
+- **Health checks**: verify actual dependency connectivity, not just "process running."
+
+## Configuration
+
+- Externalize all config. Document every knob: purpose, default, valid range, environments.
+- Sensible defaults — runnable with zero config for local dev.
+- Maintain `.env.example` with all variables and descriptions.
+- Validate required config at startup — fail fast. Log effective config (secrets masked).
+
+## Graceful Shutdown
+
+- Stop accepting new requests, drain in-flight work, release resources (12-Factor IX).

.claude/rules/15-memora.md

@@ -0,0 +1,16 @@
+# Memora Memory
+
+Use Memora proactively for persistent memory across sessions. Full instructions are in the global `~/.claude/CLAUDE.md` and `~/.claude/docs/memora-guide.md`.
+
+## Key Behaviors
+
+- **Session start:** Query existing project context via `memory_semantic_search` + `memory_list`. Follow connections — navigate the graph.
+- **During work:** Create granular memories (one per concept, not per session). Link related memories deliberately. Update existing memories instead of creating duplicates.
+- **Session end:** Capture all significant learnings. Create issues for bugs found, TODOs for incomplete work. Verify new memories are connected to existing ones.
+
+## Every Memory Must Have
+
+1. **Tags** — project identifier first, then topic tags.
+2. **Hierarchy metadata** — places the memory in the knowledge graph.
+3. **Links** — explicit connections to related memories.
+4. **Sufficient granularity** — specific enough to be actionable, with file paths and function names.

.claude/rules/16-sub-agents.md

@@ -0,0 +1,17 @@
+# Sub-Agents and Team Agents
+
+## Use Sub-Agents (Task tool) When
+
+- Independent research tasks can run in parallel.
+- A specialized agent type matches the work (e.g., debugger, test-engineer, frontend-developer).
+- The main context window would be polluted by excessive search results.
+
+## Use Team Agents When
+
+- The task benefits from multiple specialized perspectives.
+- Code review, security audit, or test analysis is warranted.
+
+## Use Direct Tools Instead When
+
+- Simple, directed searches — use Grep/Glob directly.
+- Single-file edits or tasks under 3 steps.

.claude/rules/17-document-imports.md

@@ -0,0 +1,11 @@
+# Document Import Resolution
+
+When CLAUDE.md files reference external content via `@` imports (e.g., `@docs/architecture.md`), resolve and read those imports before proceeding with the user's request.
+
+## Rules
+
+- Before acting on a user prompt, scan loaded CLAUDE.md files for `@path/to/file` references. Read any that may be relevant to the current task.
+- Treat `@docs/` references as pointers to the project's `docs/` directory.
+- When a CLAUDE.md says "documentation lives in `docs/`" or "see `docs/` for details," read the relevant docs before proceeding.
+- Do not skip imports because "the CLAUDE.md summary seems sufficient." The referenced document is the source of truth.
+- After reading imports, reconcile conflicts between the import and the CLAUDE.md summary. Flag discrepancies.