CLAUDE.md

Development guidance for Powernode subscription platform.

Project Overview

Powernode - Subscription lifecycle management platform:

Backend: Rails 8 API (./server) - JWT auth, UUIDv7 primary keys
Frontend: React TypeScript (./frontend) - Theme-aware, Tailwind CSS
Worker: Sidekiq standalone (./worker) - API-only communication
Business: Git submodule (./extensions/business) - proprietary features (billing, BaaS, reseller, AI publisher)
System: Git submodule (./extensions/system) - node lifecycle, module CRUD, fleet autonomy, on-node Go agent, initramfs, CLI. Public on GitHub (MIT) at nodealchemy/powernode-system, private on Gitea. Mounted as a submodule of this repo since 2026-05-02.
Database: PostgreSQL with native UUID schema
Payments: Stripe, PayPal with PCI compliance (business only)

Project Status: See docs/TODO.md (auto-generated from shared knowledge — do not edit manually)

Core Models

Account → User (many), Subscription (one)
Subscription → Plan, Payments, Invoices
User → Roles, Permissions, Invitations

Specialists

Use platform.discover_skills with a task description to find the right specialist capability. Fallback: MCP_CONFIGURATION.md.

Quick Reference - Critical Rules

Git Rules

NEVER commit unless explicitly requested
NEVER include Claude attribution in commits
Branch strategy: develop → feature/* → release/* → master
Tag naming: NO "v" prefix - use 0.2.0 not v0.2.0
Release branches: release/0.2.0 (no "v" prefix)
Staged commits: Group changes into logical commits by concern (models, services, controllers, frontend, tests, config) — never one monolithic commit

Business Submodule (`./extensions/business`)

Separate git repo at extensions/business/ — has its own branch, commits, and a private upstream (added manually by maintainers with access; not committed to public repo)
Always check both repos: git status in root AND git -C extensions/business status — changes in extensions/business/ are invisible to the parent repo's git status
Commit order: Commit inside extensions/business/ first, then update the submodule pointer in the parent repo
Path aliases: Business frontend uses @business/ for intra-business imports, @/ for core shared imports
Core mode: When business submodule is absent, the app runs as single-user self-hosted (all features unlocked, no billing/SaaS)
Feature gating: Shared::FeatureGateService.business_loaded? (backend), __BUSINESS__ build flag (frontend), businessOnly: true on nav items

Permission-Based Access Control (CRITICAL)

Frontend MUST use permissions ONLY - NEVER roles for access control

// ✅ CORRECT
currentUser?.permissions?.includes('users.manage')

// ❌ FORBIDDEN
currentUser?.roles?.includes('admin')
user.role === 'manager'

Backend: Use current_user.has_permission?('name') - NEVER permissions.include?() (returns objects)

Frontend Patterns

Pattern	Rule
Colors	Theme classes only: `bg-theme-`, `text-theme-`
Navigation	Flat structure - no submenus
Actions	ALL in PageContainer - none in page content
State	Global notifications only - no local success/error
Imports	Path aliases for cross-feature: `@/shared/`, `@/features/`
Logging	No `console.log` in production — use `import { logger } from '@/shared/utils/logger'` instead
Types	No `any` - proper TypeScript types required

Backend Patterns

Pattern	Rule
Controllers	`Api::V1` namespace, inherit ApplicationController
Responses	MANDATORY: `render_success()`, `render_error()`
Worker Jobs	Inherit BaseJob, use `execute()` method, API-only
Ruby Files	`# frozen_string_literal: true` pragma required
Logging	`Rails.logger` - no `puts`/`print`
Migrations	`t.references` automatically creates an index — NEVER use `add_index` for reference columns. Customize via the declaration itself: `t.references :account, index: { unique: true }`
Namespaces	ALL namespaced models MUST use `::` separator in `class_name:` — e.g., `Ai::AgentTeam` not `AiAgentTeam`, `Devops::Pipeline` not `DevopsPipeline`, `BaaS::Tenant` not `BaaSTenant`
Seeds	After modifying seeds, run `cd server && rails db:seed` and verify completion
Associations	Always pair `class_name:` with `foreign_key:` — e.g. `belongs_to :provider, class_name: "Ai::Provider", foreign_key: "ai_provider_id"`
Foreign Keys	Namespaced FK prefixes: `Ai::` → `ai_` (`ai_agent_id`), `Devops::` → `devops_` (`devops_pipeline_id`), `BaaS::` → `baas_` (`baas_customer_id`). Others: use explicit FK or omit if unambiguous
JSON Columns	Always use lambda defaults: `attribute :config, :json, default: -> { {} }` — never `default: {}`
Controller Size	Controllers MUST stay under 300 lines — extract query logic to services, serialization to concerns
Eager Loading	Always use `.includes()` when iterating associations — never bare `.all` followed by `.map`/`.each` accessing relations
Webhook Receivers	Inbound webhooks MUST return 200/202 on processing errors — NEVER 500 (causes provider retry storms)

Cryptographic Material Safety (ABSOLUTE RULES)

Rule	Details
No key output	NEVER output, log, display, echo, or transmit private keys, API secrets, seed phrases, mnemonics, or signing material in any form
No keys in code	NEVER store keys, secrets, or credentials in source code files, scripts, configs, environment files, or documentation
No CLI key generation	NEVER generate private keys via CLI commands (rails runner, rake, irb) where they could appear in shell history
Vault-only storage	ALL key generation MUST happen inside Vault or WalletKeyService (which stores directly to Vault)
Audit all key ops	ALL key operations (generate, import, revoke, sign) MUST be logged to Trading::AuditLog
No key arguments in logs	NEVER pass private keys as function arguments that could appear in logs, error messages, or exception traces
Guide, don't handle	When assisting with wallet setup, guide the user through the UI/API — never handle key material directly

Design Principles

Principle	Rule
Reuse First	`platform.discover_skills` + `platform.search_knowledge` + `platform.code_semantic_search` before proposing anything new — never standalone/greenfield when infrastructure exists
Quality Gates	Run `cd frontend && npx tsc --noEmit` after TS changes, verify Ruby syntax after .rb changes
Verify Seeds	After seed modifications: `cd server && rails db:seed` — watch for association/validation errors
Stop & Ask	HARD RULE: After 3 failed attempts at the same fix, STOP immediately and ask the user. Do NOT try a 4th approach, do NOT continue iterating, do NOT try workarounds. Present what you tried and ask for guidance
Audit Sessions	When asked to audit/review/analyze code, save findings to `docs/` and do NOT implement changes. Audit = report only, unless the user explicitly says to fix
Verify Changes	Ruby: syntax check + related spec. TypeScript: `tsc --noEmit`. Migrations: `rails db:migrate:status`. Seeds: `rails db:seed`. Use `/verify` for targeted checks
Verify CWD	Before git operations on submodules, always `git rev-parse --show-toplevel` to confirm you're in the right repo
Completion Gate	Before reporting work as done, run `/verify` on changed files. Never mark a task complete with unverified changes
Dead Reference Cleanup	After deleting any file, `grep -r` for all import/require references to it across the codebase and remove them before committing
Plan Before Multi-File	Changes touching 3+ files: outline which files will change and data flow direction, then wait for user approval before writing code. Single-file fixes can proceed directly
Parallel Investigation	When debugging spans backend + frontend or 3+ services, spawn parallel sub-agents: one per layer/service. Merge findings before proposing a fix — never serialize investigation across layers

Architecture Principles

Principle	Rule
Pull, Never Push	Downstream managers always pull from upstream sources — upstream services NEVER push to downstream. When unsure about data flow direction, ask before implementing
Extension Isolation	Each extension (`extensions/*`) is self-contained. Extensions depend on core, core NEVER depends on extensions
Service Boundaries	Cross-namespace communication goes through service interfaces, never direct model access across namespaces

Bulk Operation Safety

Rule	Details
State the count	Before ANY bulk operation (approve, reject, delete, update), always state the exact count: "This will affect N items"
Confirmation threshold	Operations affecting more than 5 items require explicit user confirmation
Show samples	For bulk operations, show the first 3 and last 1 items for verification
Never batch-approve	Training decisions, permission grants, and financial operations MUST be reviewed individually

Submodule Safety (CRITICAL)

5 submodules (all git submodules): extensions/business, extensions/trading (private remote-only), extensions/supply-chain, extensions/system, extensions/marketing (public on GitHub)
System and supply-chain extensions are publicly mirrored on GitHub — .gitmodules advertises https://github.com/nodealchemy/powernode-system.git and https://github.com/nodealchemy/powernode-supply-chain.git. Maintainer's local checkout has origin = the public GitHub mirror and ipnode = the private upstream (added manually). Push to both remotes on every release. Do NOT run git submodule sync on these submodules — it would overwrite local config and drop the private upstream remote.
Business and trading extensions are not committed to the public repo (gitignored in the parent's tree; not present in .gitmodules). Maintainers with access add them locally via git submodule add <private-url> extensions/business (and similar for trading); their commits go to the private upstream only and never appear in public clones.
CWD verification: Before EVERY git add/git commit, run git rev-parse --show-toplevel and verify it matches the intended repo
Never commit extension files from parent: Files under extensions/*/ MUST be committed from within the submodule. Running git add extensions/trading/... from parent only stages a pointer change
Commit order: Commit inside each submodule FIRST, then update pointers in parent

Terminology

Term	Meaning	Don't Confuse With
`server/`	Rails app directory on disk	Not "backend directory"
`powernode-backend`	Systemd service name (`powernode-backend@default`)	Not "server service" or "rails service"
`worker/`	Standalone Sidekiq app directory	Not "job runner"
`powernode-worker`	Systemd service name (`powernode-worker@default`)	Not "sidekiq service"

Service Management

# Systemd services (requires initial install: sudo scripts/systemd/powernode-installer.sh install)
sudo systemctl start powernode.target           # Start all services
sudo systemctl stop powernode.target            # Stop all services
sudo systemctl restart powernode-backend@default  # Restart individual service
sudo scripts/systemd/powernode-installer.sh status  # Show all service status
journalctl -u powernode-backend@default -f      # Tail service logs

NEVER use manual commands (rails server, sidekiq, npm start)

Service Operations Reference

Service	Unit Name	Port	Restart Behavior
Rails API	`powernode-backend@default`	3000	SIGUSR2 reload (~30ms) via `scripts/reload-backend.sh`. Auto-reloaded by Stop hook after `.rb` edits
Sidekiq	`powernode-worker@default`	—	Full restart (~28s drain). Wait 30s before checking status — "deactivating" is normal during drain
Worker HTTP API	`powernode-worker-web@default`	4567	If port 4567 refused, restart THIS service, not `powernode-worker`
Frontend	`powernode-frontend@default`	5173	Full restart

Stuck worker: If worker is draining >30s, use sudo systemctl stop powernode-worker@default && sudo systemctl start powernode-worker@default (stop+start, not restart) Never restart worker multiple times in quick succession — batch code changes, ONE restart at end After restart: Verify with sudo scripts/systemd/powernode-installer.sh status

Test Execution

RSpec:

cd server && bundle exec rspec --format progress    # Full suite
cd server && bundle exec rspec spec/path_spec.rb    # Single file

Frontend tests - always use CI=true:

cd frontend && CI=true npm test

Multi-Agent Test Rules

Uses DatabaseCleaner with :deletion strategy — avoids TRUNCATE deadlocks between concurrent processes.
Do NOT run multiple single-process rspec instances simultaneously on the same database.
Frontend tests (CI=true npm test) and TypeScript checks (npx tsc --noEmit) are always safe to run concurrently.

Worker Architecture (CRITICAL)

The server (server/) is a Rails API — it does NOT run Sidekiq
The worker (worker/) is a standalone Sidekiq process — it communicates with server via HTTP API only
NEVER create job classes in server/app/jobs/ — jobs belong in worker/app/jobs/
NEVER add Sidekiq gems to server/Gemfile
NEVER modify worker/ files when fixing server issues

Test Patterns Reference

Pattern	Rule
Factories	`spec/factories/` — use existing factories with traits (`:active`, `:paused`, `:archived`). AI factories in `spec/factories/ai/`
User Setup	`user_with_permissions('perm.name')` from `permission_test_helpers.rb` — never create users manually
Auth Headers	`auth_headers_for(user)` returns `{ Authorization: Bearer ... }` — use in all request specs
Response Helpers	`json_response`, `json_response_data`, `expect_success_response(data)`, `expect_error_response(msg, status)`
Shared Examples	`include_examples 'requires authentication'`, `'requires permission'`, `'scopes to current account'` — see `spec/support/shared_examples/`
AI Matchers	`be_a_valid_ai_response`, `have_execution_status(:status)`, `create_audit_log(:action)` — see `spec/support/ai_matchers.rb`
AI Helpers	`ProviderHelpers`, `AgentHelpers`, `WorkflowHelpers`, `SecurityHelpers` — see `spec/support/ai_test_helpers.rb`
E2E Pages	Page objects in `e2e/pages/` — always use existing page objects, check `e2e/pages/ai/` for AI features
E2E Selectors	`data-testid` first, then `class*="pattern"`, then `getByRole` — add `data-testid` to new components
E2E Guards	`page.on('pageerror', () => {})` in beforeEach, `if (await el.count() > 0)` for optional elements

Key Platform Documentation

Query MCP first — these files are the fallback when MCP returns no results:

Topic	MCP Query	File Fallback
MCP Configuration	`platform.discover_skills`	MCP_CONFIGURATION.md
Permission System	`platform.search_knowledge` query: "permission system"	PERMISSION_SYSTEM_REFERENCE.md
Theme System	`platform.search_knowledge` query: "theme system"	THEME_SYSTEM_REFERENCE.md
API Standards	`platform.search_knowledge` query: "API response standards"	API_RESPONSE_STANDARDS.md
UUID System	`platform.search_knowledge` query: "UUID system"	UUID_SYSTEM_IMPLEMENTATION.md
Architecture	`platform.search_knowledge_graph` query: "platform architecture"	DEVELOPMENT.md
Codebase Structure	`platform.code_context_tree` / `platform.code_semantic_search`	MCP_TOOL_CATALOG.md
Learnings & Patterns	`platform.query_learnings`	LEARNINGS.md
Shared Knowledge	`platform.search_knowledge`	KNOWLEDGE.md
Skills Registry	`platform.discover_skills`	SKILLS.md
Knowledge Graph	`platform.search_knowledge_graph`	GRAPH.md

MCP-First Development Workflow

The Powernode MCP server (platform.* tools) is the primary knowledge source. File scanning is the fallback. MCP queries are NOT optional — they are mandatory protocol steps.

SESSION START Protocol (MANDATORY — every session)

Run platform.knowledge_health — establish baseline, identify stale/conflicting knowledge
Run platform.learning_metrics — check active learnings count, recent contributions
If stale_count > 0 or conflicts detected, note them for resolution during the session
Run platform.code_index_status with repository_id: "powernode-platform" — check codebase index freshness and stale file count

BEFORE EVERY CODE CHANGE (MANDATORY)

Search existing knowledge for the area being modified — not optional, not "when convenient":
- platform.query_learnings — established patterns, anti-patterns, failure modes for this area
- platform.search_knowledge — procedures, code snippets, reference material
- platform.search_knowledge_graph — entity relationships, architecture decisions
- platform.discover_skills — reusable capabilities matching the task
- platform.code_semantic_search — find related code by meaning (e.g., "authentication middleware")
- platform.code_identifier_search — find specific classes/methods/functions by name
Understand impact before modifying:
- platform.code_blast_radius — trace every file affected by changing a symbol
- platform.code_file_skeleton — review structure of files you're about to modify
Apply discovered knowledge to your implementation approach
Fall back to file scanning only when MCP returns no relevant results
Feed file-scan discoveries back into MCP (see "After Every Task")

DURING WORK (Active Reinforcement)

When relying on a learning: Call platform.reinforce_learning with its ID immediately — this prevents decay and boosts confidence
When using shared knowledge: Call platform.rate_knowledge (4-5 if helpful, 1-2 if outdated) — this feeds quality scores
Pattern verification: Before introducing a new pattern, check platform.query_learnings
Architecture context: Before cross-cutting changes, check platform.search_knowledge_graph
Code structure: Use platform.code_context_tree to understand directory layout before adding files
Impact analysis: Use platform.code_blast_radius before renaming or refactoring shared symbols
Memory context: Use platform.search_memory to retrieve agent working memory relevant to the current task
API context: Use platform.get_api_reference to look up endpoint contracts before writing integration code
Conflict resolution: If you find two conflicting learnings, resolve with platform.resolve_contradiction immediately

AFTER EVERY TASK (MANDATORY — zero exceptions for non-trivial work)

Contribute at least one of:

When you...	Do this
Solved a non-trivial bug	`platform.create_learning` (category: `discovery` or `failure_mode`)
Established/confirmed a pattern	`platform.create_learning` (category: `pattern` or `best_practice`)
Documented a procedure or guide	`platform.create_knowledge` (content_type: `procedure`)
Found entity relationships	`platform.extract_to_knowledge_graph`
Implemented a reusable capability	`platform.create_skill`

Self-check: "Did I create learnings for the critical findings in this task?" If no, do it now.

Skip Contributions For

Trivial fixes (typos, simple renames, formatting)
Speculative or unverified analysis
Knowledge that already exists in MCP (always search first)

MCP Tool Invocation

Claude Code invokes platform.* tools directly via the streamable-http MCP server registered in .claude/settings.json (powernode entry pointing at http://localhost:3000/api/v1/mcp/message). No external daemon, no helper scripts — just call the tool by name.

MCP Tool Catalog

All platform.* tools organized by development task. Full parameter docs: MCP_TOOL_CATALOG.md.

Discovery & Context (10 tools)

Tool	Description
`search_knowledge`	Semantic search across shared knowledge entries
`query_learnings`	Query compound learnings by category, status, or text
`search_knowledge_graph`	Semantic search over knowledge graph nodes
`reason_knowledge_graph`	Multi-hop reasoning across graph relationships
`discover_skills`	Find reusable skills matching a task description
`get_skill_context`	Get full execution context for a specific skill
`search_memory`	Search agent working/shared memory pools
`search_documents`	Search RAG document chunks by query
`query_knowledge_base`	Query a specific knowledge base with RAG
`get_api_reference`	Look up API endpoint contracts and schemas

Knowledge Contribution (7 tools)

Tool	Description
`create_learning`	Create a compound learning (categories: `pattern`, `best_practice`, `discovery`, `failure_mode`)
`create_knowledge`	Create a shared knowledge entry (content_types: `procedure`, `reference`, `guide`)
`update_knowledge`	Update an existing shared knowledge entry
`promote_knowledge`	Promote knowledge for cross-team visibility
`extract_to_knowledge_graph`	Extract entities and relationships to the knowledge graph
`create_skill`	Register a reusable skill with execution context
`update_skill`	Update an existing skill definition

Quality & Reinforcement (9 tools)

Tool	Description
`verify_learning`	Verify a learning as accurate (boosts confidence)
`dispute_learning`	Dispute an inaccurate learning with reason
`resolve_contradiction`	Pick a winner between two conflicting learnings
`rate_knowledge`	Rate shared knowledge quality (1-5 scale)
`reinforce_learning`	Reinforce a learning that was used successfully
`knowledge_health`	Cross-system health report (learnings + knowledge + graph)
`learning_metrics`	Compound learning statistics and trends
`skill_health`	Skill system health and conflict report
`skill_metrics`	Skill usage statistics and effectiveness

Agent Management (5 tools)

Tool	Description
`create_agent`	Create a new AI agent with provider and model config
`list_agents`	List agents (filterable by status, provider)
`get_agent`	Get full agent details including trust score
`update_agent`	Update agent configuration
`execute_agent`	Execute an agent with a prompt and optional tools

Team Management (6 tools)

Tool	Description
`create_team`	Create an agent team with composition rules
`list_teams`	List teams (filterable by status)
`get_team`	Get team details including members and roles
`update_team`	Update team configuration
`add_team_member`	Add an agent to a team with a role
`execute_team`	Execute a team task with orchestration

Knowledge Graph Exploration (7 tools)

Tool	Description
`search_knowledge_graph`	Semantic search over graph nodes
`reason_knowledge_graph`	Multi-hop reasoning across relationships
`get_graph_node`	Get a specific node with its relationships
`list_graph_nodes`	List graph nodes (filterable by type, label)
`get_graph_neighbors`	Get connected nodes within N hops
`graph_statistics`	Graph-wide statistics (node/edge counts, density)
`get_subgraph`	Extract a subgraph around a focal node

Memory Management (6 tools)

Tool	Description
`write_shared_memory`	Write to a shared memory pool (key-value with TTL)
`read_shared_memory`	Read from a shared memory pool by key
`search_memory`	Semantic search across memory entries
`consolidate_memory`	Trigger memory tier consolidation (STM→LTM)
`memory_stats`	Memory usage statistics per tier
`list_pools`	List available memory pools for an agent/team

RAG & Documents (7 tools)

Tool	Description
`query_knowledge_base`	Query a knowledge base using RAG retrieval
`list_knowledge_bases`	List available knowledge bases
`create_knowledge_base`	Create a new knowledge base
`add_document`	Add a document to a knowledge base
`process_document`	Trigger document chunking and embedding
`search_documents`	Search document chunks by semantic query
`delete_document`	Remove a document from a knowledge base

Content Management (8 tools)

Tool	Description
`list_kb_articles`	List knowledge base articles
`get_kb_article`	Get article content and metadata
`create_kb_article`	Create a new KB article
`update_kb_article`	Update an existing KB article
`list_pages`	List content pages
`get_page`	Get page content and metadata
`create_page`	Create a new content page
`update_page`	Update an existing content page

Skill Administration (4 tools)

Tool	Description
`list_skills`	List skills with pagination and filters
`get_skill`	Get full skill definition and execution context
`delete_skill`	Remove a skill
`toggle_skill`	Enable or disable a skill

AI Autonomy & Safety (16 tools)

Tool	Description
`emergency_halt`	Emergency halt ALL AI activity (kill switch)
`emergency_resume`	Resume AI activity after emergency halt
`kill_switch_status`	Check current kill switch state
`create_agent_goal`	Create a goal for an agent (self or managed)
`list_agent_goals`	List an agent's goals (introspection)
`update_agent_goal`	Update goal progress or status
`agent_introspect`	View own execution history, trust score, performance, and budget
`propose_feature`	Create a feature suggestion for human review
`send_proactive_notification`	Notify users about detected issues or suggestions
`discover_claude_sessions`	Find active Claude Code MCP client sessions
`request_code_change`	Request code changes via workspace message
`create_proposal`	Formally propose a change for human review
`escalate`	Structured escalation when stuck or encountering issues
`request_feedback`	Request user feedback on completed work
`report_issue`	Report a detected platform issue

Codebase Intelligence (14 tools)

Tool	Description
`code_context_tree`	AST-based structural tree with file headers and symbol ranges (depth-pruned)
`code_file_skeleton`	Function signatures, class methods, type definitions with line ranges (no bodies)
`code_semantic_search`	Semantic search over code symbols using embeddings — finds code by meaning
`code_identifier_search`	Search identifiers (functions, classes, variables) by name with usage counts
`code_semantic_navigate`	Browse codebase by meaning using semantic clustering with labeled groups
`code_feature_hub`	Obsidian-style feature navigation from markdown `[[wikilinks]]`
`code_blast_radius`	Trace every file and line where a symbol is imported or used — impact analysis
`code_static_analysis`	Run native linters/compilers (RuboCop, TypeScript, ESLint) with structured output
`code_index_status`	Codebase index statistics: files indexed, symbols, staleness, embedding coverage
`code_upsert_node`	Create/update a code-aware knowledge graph node with auto-embedding
`code_create_relation`	Create typed edges between code nodes (imports, calls, inherits, etc.)
`code_search_graph`	Search code graph with optional multi-hop traversal
`code_prune_stale`	Find/archive nodes for files that no longer exist (dry_run supported)
`code_bulk_index`	Trigger codebase indexing — AST parse, create KG nodes/edges, generate embeddings

DevOps & CI/CD (6 tools)

Tool	Description
`create_gitea_repository`	Create a Gitea repository (private by default)
`update_gitea_repository`	Update Gitea repo settings (visibility, description, archival)
`dispatch_to_runner`	Dispatch a job to a Git runner (GitHub/Gitea)
`trigger_pipeline`	Trigger a CI/CD pipeline run
`list_pipelines`	List pipelines (filterable by status)
`get_pipeline_status`	Get pipeline run status and step details

Docker Management (52 tools)

Tool	Description
`docker_list_containers`	List all containers on a host with status, image, ports
`docker_get_container`	Detailed info on a specific container
`docker_create_container`	Create a new container from an image
`docker_start_container`	Start a stopped container
`docker_stop_container`	Stop a running container (configurable timeout)
`docker_restart_container`	Restart a container
`docker_remove_container`	Remove a container (force flag available)
`docker_container_logs`	Retrieve container logs (tail + since filters)
`docker_container_stats`	Live CPU, memory, network I/O stats
`docker_container_exec`	Execute a command inside a running container
`docker_list_services`	List all Swarm services with replica counts
`docker_get_service`	Detailed info on a specific Swarm service
`docker_create_service`	Create a service with image, replicas, ports, env
`docker_update_service`	Update service config (image, env, constraints)
`docker_scale_service`	Scale a service to a specified replica count
`docker_rollback_service`	Rollback a service to its previous version
`docker_remove_service`	Remove a service and its tasks
`docker_service_logs`	Retrieve aggregated logs from all service tasks
`docker_service_tasks`	List tasks with status and node placement
`docker_list_stacks`	List all stacks with status and service count
`docker_get_stack`	Detailed stack info including compose file
`docker_deploy_stack`	Deploy or redeploy a stack from Compose YAML
`docker_remove_stack`	Remove a stack and all its services
`docker_adopt_stack`	Adopt an externally-deployed stack into Powernode
`docker_list_clusters`	List all Swarm clusters with connection status
`docker_get_cluster`	Detailed cluster info with node/service counts
`docker_cluster_health`	Comprehensive health check (nodes, services, alerts)
`docker_list_nodes`	List all nodes with role, availability, resources
`docker_node_promote`	Promote a worker node to manager
`docker_node_demote`	Demote a manager node to worker
`docker_node_drain`	Drain a node (stop scheduling, migrate tasks)
`docker_node_activate`	Activate a drained node to resume scheduling
`docker_list_secrets`	List secrets (metadata only, not values)
`docker_create_secret`	Create a new Swarm secret
`docker_remove_secret`	Remove a secret
`docker_list_configs`	List all Swarm configs
`docker_create_config`	Create a new Swarm config
`docker_remove_config`	Remove a config
`docker_list_hosts`	List all Docker hosts with connection status
`docker_get_host`	Detailed host info (OS, resources, Docker version)
`docker_sync_host`	Sync containers and images from Docker daemon
`docker_test_host`	Test connection to a Docker host
`docker_list_images`	List all images with tags, size, creation time
`docker_pull_image`	Pull an image from a registry
`docker_remove_image`	Remove an image (force flag available)
`docker_tag_image`	Tag an image with a new repository and tag
`docker_list_networks`	List Swarm networks with driver and scope
`docker_create_network`	Create an overlay network
`docker_remove_network`	Remove a network
`docker_list_volumes`	List Swarm volumes with driver info
`docker_create_volume`	Create a volume with configurable driver
`docker_remove_volume`	Remove a volume

Knowledge Quality Lifecycle

The platform runs automated maintenance (see worker/config/sidekiq.yml). Claude Code participates in the quality loop:

Automated (background jobs)

Job	Schedule	Effect
Compound learning decay	3:45 AM daily	`importance_score` decays exponentially on stale learnings
Memory consolidation	4:00 AM daily	Promotes STM→long-term (access>=3), deduplicates (similarity>=0.92)
Rot detection	4:00 AM daily	Auto-archives context entries with staleness>=0.9
Trust score decay	2:00 AM daily	Decays idle agent trust scores
Skill lifecycle	4:15 AM daily / 5 AM weekly / 3 AM monthly	Conflict scan, stale decay, re-embedding, gap detection
Shared knowledge maintenance	Daily	Import from learnings, recalculate quality scores, audit stale entries
Escalation timeout	Every 15 min	Auto-escalate overdue escalations
Goal maintenance	Every 6 hours	Auto-abandon stale goals
Intervention policy tuning	Weekly	Analyze approval patterns and suggest policy adjustments
Observation pipeline	Every 30 min	Collect sensor data for autonomous agents
Observation cleanup	Daily	Delete expired and old processed observations
Proposal expiry	Every hour	Expire overdue unreviewed proposals

Manual (Claude Code responsibilities)

Trigger	Action	Tool
Used a learning successfully	Reinforce it	`platform.reinforce_learning`
Used a learning that was wrong	Dispute it	`platform.dispute_learning`
Found two conflicting learnings	Resolve the conflict	`platform.resolve_contradiction`
Read useful shared knowledge	Rate it 4-5	`platform.rate_knowledge`
Read outdated shared knowledge	Rate it 1-2, create corrected version	`platform.rate_knowledge` + `platform.create_knowledge`
Periodic health check	Run diagnostics	`platform.knowledge_health` + `platform.skill_health`
Found stale/wrong code patterns	Fix code, then document the fix	Fix → `platform.create_learning` (category: `discovery`)
Removed deprecated code	Document removal	`platform.create_learning` (category: `pattern`)

Proactive Maintenance (during sessions)

Before starting work: Run platform.knowledge_health if last check was >24h ago
When encountering bugs: Always search platform.query_learnings for existing fix — if found, reinforce_learning; if not, fix and create_learning
When removing stale code: Create a learning documenting what was removed and why
When fixing documentation: Update platform.update_knowledge to correct the source entry

Tool Evolution

All platform.* tools are defined in server/app/services/ai/tools/platform_api_tool_registry.rb. When tools are added/modified, run cd server && rails mcp:generate_tool_catalog to regenerate docs/platform/MCP_TOOL_CATALOG.md. When MCP knowledge is updated significantly, run cd server && rails mcp:sync_docs to regenerate fallback docs in docs/platform/knowledge/. Knowledge sync runs automatically daily at 5:30 AM UTC via AiKnowledgeDocSyncJob.

Adding a New Tool

Create tool class in server/app/services/ai/tools/
Add action→class mapping to PlatformApiToolRegistry::TOOLS
Add action_definitions with descriptions and parameter schemas
Run rails mcp:generate_tool_catalog → updates docs/platform/MCP_TOOL_CATALOG.md
Update relevant CLAUDE.md component file(s) with the new tool
Create learning: platform.create_learning category: pattern documenting the new tool

Deprecating a Tool

Add deprecation notice to action_definitions description
Create learning: platform.create_learning category: best_practice documenting the replacement
Remove from CLAUDE.md after migration period

File Organization

NEVER save files to project root. Use:

docs/platform/ - Platform architecture
docs/backend/ - Backend documentation
docs/frontend/ - Frontend documentation
docs/testing/ - Testing documentation
docs/services/ - Service documentation
docs/infrastructure/ - Infrastructure documentation

Automation Scripts

# Code quality
./scripts/pre-commit-quality-check.sh    # Run all checks
./scripts/fix-hardcoded-colors.sh        # Fix theme violations
./scripts/cleanup-all-console-logs.sh    # Remove console.log
./scripts/convert-relative-imports.sh    # Fix import paths

# Pattern validation
./scripts/pattern-validation.sh          # Full audit
./scripts/quick-pattern-check.sh         # Quick check

# Pre-push validation
./scripts/validate.sh                    # Run all checks (specs + TS + patterns)
./scripts/validate.sh --skip-tests       # Skip RSpec, run TS + patterns only

# Service management (systemd)
sudo scripts/systemd/powernode-installer.sh install           # Install units + configs
sudo scripts/systemd/powernode-installer.sh add-instance backend api2  # Add instance
sudo scripts/systemd/powernode-installer.sh status            # Show all services

FilesExpand file tree

CLAUDE.md

Latest commit

History

CLAUDE.md

File metadata and controls

CLAUDE.md

Project Overview

Core Models

Specialists

Quick Reference - Critical Rules

Git Rules

Business Submodule (./extensions/business)

Permission-Based Access Control (CRITICAL)

Frontend Patterns

Backend Patterns

Cryptographic Material Safety (ABSOLUTE RULES)

Design Principles

Architecture Principles

Bulk Operation Safety

Submodule Safety (CRITICAL)

Terminology

Service Management

Service Operations Reference

Test Execution

Multi-Agent Test Rules

Worker Architecture (CRITICAL)

Test Patterns Reference

Key Platform Documentation

MCP-First Development Workflow

SESSION START Protocol (MANDATORY — every session)

BEFORE EVERY CODE CHANGE (MANDATORY)

DURING WORK (Active Reinforcement)

AFTER EVERY TASK (MANDATORY — zero exceptions for non-trivial work)

Skip Contributions For

MCP Tool Invocation

MCP Tool Catalog

Discovery & Context (10 tools)

Knowledge Contribution (7 tools)

Quality & Reinforcement (9 tools)

Agent Management (5 tools)

Team Management (6 tools)

Knowledge Graph Exploration (7 tools)

Memory Management (6 tools)

RAG & Documents (7 tools)

Content Management (8 tools)

Skill Administration (4 tools)

AI Autonomy & Safety (16 tools)

Codebase Intelligence (14 tools)

DevOps & CI/CD (6 tools)

Docker Management (52 tools)

Knowledge Quality Lifecycle

Automated (background jobs)

Manual (Claude Code responsibilities)

Proactive Maintenance (during sessions)

Tool Evolution

Adding a New Tool

Deprecating a Tool

File Organization

Automation Scripts

Business Submodule (`./extensions/business`)