lywsvip/ironclaw
1
0
Fork 0
mirror of https://github.com/nearai/ironclaw.git synced 2026-09-03 08:06:01 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: update OpenWiki wiki

Browse Source
This commit is contained in:
serrrfirat
2026-08-24 08:19:19 +00:00
committed by github-actions[bot]
parent a1e3ca5bf5
commit 8f2fe99b18
10 changed files with 178 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
openwiki/.last-update.json
View File

@@ -1,6 +1,8 @@
{
"updatedAt": "2026-07-06T16:59:47.000Z",
"updatedAt": "2026-08-24T08:18:53.956Z",
"command": "update",
"gitHead": "22102e9c9c062e1a1fb263e0631f22a9dfddcbe6",
"model": "claude-opus-4"
"gitHead": "a1e3ca5bf5ff18571ab6b4777c302129b91fdea4",
"model": "claude-haiku-4-5",
"status": "complete",
"language": "en"
}

56
openwiki/architecture/crates.md
View File

@@ -1,3 +1,9 @@
---
type: "Reference"
title: "Crate Reference"
openwiki_generated: true
---
# Crate Reference
This page documents all 68+ crates in the IronClaw repository, organized by functional group. Use this as a reference when exploring code or deciding where to add new features.
@@ -55,13 +61,29 @@ This page documents all 68+ crates in the IronClaw repository, organized by func
- **Depends on:** serde, toml
### ironclaw_architecture_tests
**Role:** Architecture boundary tests and enforcement
- Dependency graph checking
- Composition boundary tests
- Reborn vs v1 boundary enforcement
- **When to touch:** Refactoring crate dependencies
- **Key modules:** `tests/reborn_composition_boundaries.rs`
- **Tests:** Run with `cargo test -p ironclaw_architecture_tests --test '*'`
**Role:** Architecture contract enforcement — validates that the crate dependency graph, composition boundaries, and public surfaces remain aligned with the declared Reborn design model. This is the mechanical gate that prevents architectural drift.
**Responsibilities:**
- **Dependency boundaries:** Enforces layer-by-layer dependency direction (substrate ← kernel ← userland ← products; no circular deps)
- **Composition boundaries:** Tests that each crate publishes only the types and traits it owns (prevents accidental coupling)
- **Extension specificity:** Scans source code to ban concrete extension names (vendor, host) in product code — catches hardcoded integrations that should use registries
- **Contract ratchets:** Records baseline counts (e.g., number of authorized-seal origination sites) and fails the build if the count increases, forcing deliberate re-baselineing in the PR that increases it
- **Sealed evidence:** Verifies that security-critical types (e.g., `AuthorizedSeal`) can only be minted from approved locations
- **Persistence rules:** Ensures consistent use of event-sourcing and stored procedures patterns across backends (PostgreSQL vs. libSQL)
**When to touch:**
- Refactoring crate dependencies (add/remove edges)
- Adding a new crate (register in the layer/family model)
- Moving a crate to a different family/layer (update boundary rules)
- Approving new extension integration patterns (update allowlists in the same PR as the pattern)
**Key tests:** `reborn_dependency_boundaries`, `reborn_composition_boundaries`, `reborn_extension_specificity`, `reborn_sealed_evidence_mint_ratchet`, `reborn_authorized_seal_ratchet`
**Zero production surface:** This crate ships no runtime code; it is consumed only by CI/CD. Every test reads the workspace structure and source text without linking any crate.
**Run:** `cargo test -p ironclaw_architecture_tests` (full suite) or `cargo test -p ironclaw_architecture_tests --test reborn_composition_boundaries` (single test)
**See also:** `crates/app/ironclaw_architecture_tests/README.md` (full gate documentation), `docs/internal/reborn/contracts/` (design contracts and allowed architecture changes)
---
@@ -467,6 +489,22 @@ This page documents all 68+ crates in the IronClaw repository, organized by func
- **Features:** `webui-v2-beta` (for serve command), `slack-v2-host-beta` (for Slack)
- **Depends on:** `ironclaw_reborn`, `ironclaw_config`, `clap`
### ironclaw_webui
**Role:** WebUI HTTP server and single-page application (the browser interface)
- HTTP server entrypoint and middleware stack (auth, rate limiting, CORS)
- 114+ routes serving the Vite-built SPA
- Session management, OAuth integration, bearer token auth
- Web debug inspector for development
- **When to touch:** Adding routes, changing auth model, updating SPA, or modifying middleware
- **Frontend:** Vite SPA under `frontend/` with TypeScript, React, component library
- **Component Library:** Documented in Storybook (~31 stories covering design tokens, primitives, composites, and icons)
- **Build:** Embedded SPA is compiled by `build.rs` via `pnpm build` and embedded in the binary
- **Tests:** Route table contract (all routes registered), product symbol boundary (frozen at 104 symbols), authentication flows
- **Testing Frontend:** `pnpm test` (unit tests), `pnpm test:storybook` (visual component tests in headless Chromium), `pnpm build-storybook` (static catalog)
- **Key modules:** `src/webui_v2/` (routes, auth, handlers), `frontend/src/` (React components, pages)
- **Depends on:** `ironclaw_product_contracts`, `ironclaw_auth`, `axum`, `ironclaw_extensions_host`
- **Invariants:** Route table is a contract (add routes in handlers + route descriptor); product symbol boundary pinned at 104 symbols (architecture test `reborn_transport_product_boundary` enforces this)
### ironclaw_config
**Role:** Configuration parsing and resolution
- `config.toml` parsing
@@ -814,7 +852,9 @@ subscriber.subscribe(filter, |event| async {
1. **To understand the overall architecture:** Start with [overview.md](overview.md)
2. **To understand a specific crate:** Find it in this reference
3. **To add a new feature:** Use [overview.md: Where to Build New Features](overview.md#where-to-build-new-features) to pick a crate, then read its docs
<!-- openwiki: broken internal link [data-model.md] file "data-model.md" does not exist. Fix the href or restore the target, then delete this comment. -->
4. **To understand data flow:** Read [data-model.md](data-model.md)
<!-- openwiki: broken internal link [security.md] file "security.md" does not exist. Fix the href or restore the target, then delete this comment. -->
5. **To understand security:** Read [security.md](security.md)
---
@@ -822,7 +862,9 @@ subscriber.subscribe(filter, |event| async {
## See Also
- **[Overview](overview.md)** — System design and four-layer model
<!-- openwiki: broken internal link [data-model.md] file "data-model.md" does not exist. Fix the href or restore the target, then delete this comment. -->
- **[Data Model](data-model.md)** — Events, threads, turns, capabilities
<!-- openwiki: broken internal link [security.md] file "security.md" does not exist. Fix the href or restore the target, then delete this comment. -->
- **[Security & Safety](security.md)** — Kernel boundary and threat model
- **[AGENTS.md](/AGENTS.md)** — Quick rules and code discovery
- **[CLAUDE.md](/CLAUDE.md)** — Subsystem deep-dives

4
openwiki/architecture/index.md Normal file
View File

@@ -0,0 +1,4 @@
# Files
- [Crate Reference](crates.md)
- [Architecture Overview](overview.md)

8
openwiki/architecture/overview.md
View File

@@ -1,3 +1,9 @@
---
type: "Reference"
title: "Architecture Overview"
openwiki_generated: true
---
# Architecture Overview
This page explains IronClaw's system design, the four-layer model, dependency structure, and where to build new features.
@@ -388,7 +394,9 @@ MemoryStore (Native | Bedrock | Pinecone | ...)
## See Also
- **[Crate Reference](crates.md)** — Detailed breakdown of all 68+ crates
<!-- openwiki: broken internal link [data-model.md] file "data-model.md" does not exist. Fix the href or restore the target, then delete this comment. -->
- **[Data Model](data-model.md)** — Events, threads, turns, capabilities
<!-- openwiki: broken internal link [security.md] file "security.md" does not exist. Fix the href or restore the target, then delete this comment. -->
- **[Security & Safety](security.md)** — Kernel boundary, threat model, approval gates
- **[AGENTS.md](/AGENTS.md)** — Quick rules and code discovery
- **[CLAUDE.md](/CLAUDE.md)** — Subsystem deep-dives by crate/module

5
openwiki/development/index.md Normal file
View File

@@ -0,0 +1,5 @@
# Files
- [Development Setup](setup.md)
- [Testing Guide](testing.md)
- [Development Workflows](workflows.md)

7
openwiki/development/setup.md
View File

@@ -1,3 +1,9 @@
---
type: "Reference"
title: "Development Setup"
openwiki_generated: true
---
# Development Setup
This page covers setting up your local development environment for IronClaw.
@@ -406,6 +412,7 @@ chmod +x scripts/dev-setup.sh
## Next Steps
- **Run tests:** `cargo test --lib` (should pass)
<!-- openwiki: broken internal link [/AGENTS.md#repo-wide-coding-rules] heading anchor "repo-wide-coding-rules" does not exist in "/AGENTS.md". Fix the href or restore the target, then delete this comment. -->
- **Review code style:** Read [AGENTS.md](/AGENTS.md#repo-wide-coding-rules)
- **Set up your IDE:** Follow IDE-specific instructions above
- **Configure your editor:** Enable clippy and fmt on save

51
openwiki/development/testing.md
View File

@@ -1,3 +1,9 @@
---
type: "Reference"
title: "Testing Guide"
openwiki_generated: true
---
# Testing Guide
This guide covers IronClaw's testing strategy, test tiers, patterns, and how to write tests for different parts of the system.
@@ -39,6 +45,18 @@ IronClaw has three tiers of tests:
- **When to use:** Testing complete workflows that the user would perform
- **Example:** Test that a Slack message flows through to a tool execution and back
### Tier 4: Architecture Boundary Tests (Mechanical, Structural)
- **Purpose:** Enforce the declared Reborn design model — validate layer/dependency direction, composition boundaries, extension specificity, and contract seals
- **Speed:** <2 seconds each
- **Count:** 37+ boundary gates organized across dedicated test files
- **External:** None (reads workspace structure and source text)
- **Command:** `cargo test -p ironclaw_architecture_tests`
- **When to use:** Whenever refactoring dependencies, adding a new crate, or approving new extension patterns
- **What it catches:** Accidental circular dependencies, breaking layer boundaries, hardcoded extension names (should use registries), unauthorized mint points for security types
- **Example:** When moving a crate to a different layer or adding a new integration pattern, the boundary tests fail with exact guidance on what rule was broken and how to fix it or update the allowlist
- **Key tests:** `reborn_dependency_boundaries`, `reborn_composition_boundaries`, `reborn_extension_specificity`, `reborn_sealed_evidence_mint_ratchet`
- **Note:** Runs automatically in CI and in the pre-push hook. Part of normal `cargo test` if you `cargo test -p '*'`, but usually skipped unless you're refactoring architecture.
## Running Tests
### Quick Smoke Test
@@ -69,6 +87,18 @@ IRONCLAW_HOOKS_POSTGRES_URL="postgres://ironclaw:ironclaw@127.0.0.1:5432/ironcla
cargo test -- --ignored
```
### Architecture Boundary Tests
```bash
# Run the full architecture test suite
cargo test -p ironclaw_architecture_tests
# Run a specific boundary test
cargo test -p ironclaw_architecture_tests --test reborn_dependency_boundaries
# Run all tests matching a pattern
cargo test -p ironclaw_architecture_tests reborn_extension
```
### Single Test or Module
```bash
# Run one test
@@ -84,6 +114,24 @@ cargo test --test executor_happy_paths
cargo test --lib safety
```
### WebUI Frontend Tests
```bash
# Navigate to the frontend directory
cd crates/product/ironclaw_webui/frontend
# Run unit and component tests (vitest)
pnpm test
# Run Storybook visual component tests in headless Chromium
pnpm test:storybook
# Start Storybook dev server (interactive catalog at http://localhost:6006)
pnpm storybook
# Build static Storybook catalog
pnpm build-storybook
```
### Watch Mode
```bash
# Re-run tests on file changes
@@ -589,9 +637,12 @@ Find the cause:
## See Also
- **[Setup Guide](setup.md)** — How to set up your environment
<!-- openwiki: broken internal link [workflows.md#code-review] heading anchor "code-review" does not exist in "workflows.md". Fix the href or restore the target, then delete this comment. -->
- **[Workflows: Code Review](workflows.md#code-review)** — How to review tests in PRs
<!-- openwiki: broken internal link [/AGENTS.md#test-discipline] heading anchor "test-discipline" does not exist in "/AGENTS.md". Fix the href or restore the target, then delete this comment. -->
- **[AGENTS.md: Testing](/AGENTS.md#test-discipline)** — Testing discipline rules
- **[COVERAGE_PLAN.md](/COVERAGE_PLAN.md)** — Coverage goals and strategy
<!-- openwiki: broken internal link [/tests/e2e/CLAUDE.md] file "/tests/e2e/CLAUDE.md" does not exist. Fix the href or restore the target, then delete this comment. -->
- **[tests/e2e/CLAUDE.md](/tests/e2e/CLAUDE.md)** — E2E test documentation
---

7
openwiki/development/workflows.md
View File

@@ -1,3 +1,9 @@
---
type: "Reference"
title: "Development Workflows"
openwiki_generated: true
---
# Development Workflows
This page covers common development tasks: fixing bugs, adding features, code review, and deployment.
@@ -310,6 +316,7 @@ fn test_issue_is_fixed() {
The safety layer is high-risk. Follow this process:
<!-- openwiki: broken internal link [/crates/ironclaw_safety/CLAUDE.md] file "/crates/ironclaw_safety/CLAUDE.md" does not exist. Fix the href or restore the target, then delete this comment. -->
1. **Understand current behavior:** Read [crates/ironclaw_safety/CLAUDE.md](/crates/ironclaw_safety/CLAUDE.md)
2. **Write tests first:**

12
openwiki/index.md Normal file
View File

@@ -0,0 +1,12 @@
---
okf_version: "0.1"
---
# Files
- [IronClaw OpenWiki: Quick Start](quickstart.md)
# Directories
- [architecture](architecture/)
- [development](development/)

30
openwiki/quickstart.md
View File

@@ -1,3 +1,9 @@
---
type: "Reference"
title: "IronClaw OpenWiki: Quick Start"
openwiki_generated: true
---
# IronClaw OpenWiki: Quick Start
Welcome to the IronClaw repository documentation. This is your entry point to understanding the codebase structure, how to build and test, and where to find help.
@@ -46,7 +52,9 @@ ironclaw/
- **[Architecture Overview](architecture/overview.md)** — High-level system design, four-layer model, crate organization
- **[Crate Reference](architecture/crates.md)** — Detailed breakdown of 68 crates, their purpose, and key types
<!-- openwiki: broken internal link [architecture/data-model.md] file "architecture/data-model.md" does not exist. Fix the href or restore the target, then delete this comment. -->
- **[Data Model](architecture/data-model.md)** — Events, runs, threads, turns, capabilities, and state flows
<!-- openwiki: broken internal link [architecture/security.md] file "architecture/security.md" does not exist. Fix the href or restore the target, then delete this comment. -->
- **[Security & Safety](architecture/security.md)** — Kernel/userland boundary, policy enforcement, threat model
### 🛠️ Building and Testing
@@ -57,17 +65,26 @@ ironclaw/
### 📚 Domain Deep Dives
<!-- openwiki: broken internal link [domains/agent-loop.md] file "domains/agent-loop.md" does not exist. Fix the href or restore the target, then delete this comment. -->
- **[Agent Loop & Execution](domains/agent-loop.md)** — How turns flow through planning, execution, and checkpointing
<!-- openwiki: broken internal link [domains/capabilities.md] file "domains/capabilities.md" does not exist. Fix the href or restore the target, then delete this comment. -->
- **[Capabilities & Tools](domains/capabilities.md)** — How tools are registered, approved, and executed
<!-- openwiki: broken internal link [domains/memory.md] file "domains/memory.md" does not exist. Fix the href or restore the target, then delete this comment. -->
- **[Memory & Persistence](domains/memory.md)** — Event store, snapshots, recovery, and indexing
<!-- openwiki: broken internal link [domains/product-workflow.md] file "domains/product-workflow.md" does not exist. Fix the href or restore the target, then delete this comment. -->
- **[Product Workflow](domains/product-workflow.md)** — Missions, projects, skills, routines, and approvals
<!-- openwiki: broken internal link [domains/channels.md] file "domains/channels.md" does not exist. Fix the href or restore the target, then delete this comment. -->
- **[Channels & Integrations](domains/channels.md)** — Slack, WebUI, Discord, and custom channel adapters
### 📖 Reference
<!-- openwiki: broken internal link [reference/glossary.md] file "reference/glossary.md" does not exist. Fix the href or restore the target, then delete this comment. -->
- **[Glossary](reference/glossary.md)** — Key terminology and concepts
<!-- openwiki: broken internal link [reference/api.md] file "reference/api.md" does not exist. Fix the href or restore the target, then delete this comment. -->
- **[API Surface](reference/api.md)** — HTTP endpoints, WebSocket events, CLI commands
<!-- openwiki: broken internal link [reference/configuration.md] file "reference/configuration.md" does not exist. Fix the href or restore the target, then delete this comment. -->
- **[Configuration](reference/configuration.md)** — Startup options, environment variables, and config.toml schema
<!-- openwiki: broken internal link [reference/troubleshooting.md] file "reference/troubleshooting.md" does not exist. Fix the href or restore the target, then delete this comment. -->
- **[Troubleshooting](reference/troubleshooting.md)** — Common errors, debugging tips, and support
## Key Architectural Concepts
@@ -116,12 +133,18 @@ Substrate Layer (Events, Filesystem, Memory, Threads)
### I want to...
<!-- openwiki: broken internal link [development/workflows.md#fixing-a-bug] heading anchor "fixing-a-bug" does not exist in "development/workflows.md". Fix the href or restore the target, then delete this comment. -->
- **Fix a bug:** Jump to [Workflows: Fix a Bug](development/workflows.md#fixing-a-bug) (test-first discipline required)
- **Add a new feature:** See [Architecture Overview](architecture/overview.md#where-to-build-new-features) and [Crate Reference](architecture/crates.md)
<!-- openwiki: broken internal link [development/workflows.md#code-review] heading anchor "code-review" does not exist in "development/workflows.md". Fix the href or restore the target, then delete this comment. -->
- **Review a pull request:** Read [Workflows: Code Review](development/workflows.md#code-review) and the [Testing Guide](development/testing.md)
<!-- openwiki: broken internal link [reference/configuration.md] file "reference/configuration.md" does not exist. Fix the href or restore the target, then delete this comment. -->
- **Deploy to production:** See [Configuration](reference/configuration.md) and Dockerfile patterns in `crates/ironclaw_cli`
<!-- openwiki: broken internal link [domains/capabilities.md] file "domains/capabilities.md" does not exist. Fix the href or restore the target, then delete this comment. -->
- **Understand a capability:** Visit [Capabilities & Tools](domains/capabilities.md)
<!-- openwiki: broken internal link [AGENTS.md#code-discovery] file "AGENTS.md" does not exist. Fix the href or restore the target, then delete this comment. -->
- **Query the codebase:** Use the knowledge graph (see [AGENTS.md: Code Discovery](AGENTS.md#code-discovery)) before grep
<!-- openwiki: broken internal link [architecture/security.md] file "architecture/security.md" does not exist. Fix the href or restore the target, then delete this comment. -->
- **Report a security issue:** See [Security & Safety](architecture/security.md) and SECURITY.md (if present)
## Important Rules & Practices
@@ -197,16 +220,22 @@ openwiki/
|----------|-----------|
| "What does this crate do?" | [Crate Reference](architecture/crates.md) |
| "How do I run tests?" | [Testing Guide](development/testing.md) |
<!-- openwiki: broken internal link [architecture/security.md] file "architecture/security.md" does not exist. Fix the href or restore the target, then delete this comment. -->
| "What's the security model?" | [Security & Safety](architecture/security.md) |
<!-- openwiki: broken internal link [domains/capabilities.md] file "domains/capabilities.md" does not exist. Fix the href or restore the target, then delete this comment. -->
| "How do capabilities work?" | [Capabilities & Tools](domains/capabilities.md) |
<!-- openwiki: broken internal link [/AGENTS.md#where-to-work] heading anchor "where-to-work" does not exist in "/AGENTS.md". Fix the href or restore the target, then delete this comment. -->
| "Where do I add a new feature?" | [Architecture Overview](architecture/overview.md#where-to-build-new-features) + [AGENTS.md: Where to Work](/AGENTS.md#where-to-work) |
<!-- openwiki: broken internal link [reference/troubleshooting.md] file "reference/troubleshooting.md" does not exist. Fix the href or restore the target, then delete this comment. -->
| "What's this error?" | [Troubleshooting](reference/troubleshooting.md) |
<!-- openwiki: broken internal link [reference/glossary.md] file "reference/glossary.md" does not exist. Fix the href or restore the target, then delete this comment. -->
| "What's a 'turn'?" | [Glossary](reference/glossary.md) |
### Direct Code Exploration
When these docs don't answer your question:
<!-- openwiki: broken internal link [/AGENTS.md#code-discovery---query-the-knowledge-graph-first] heading anchor "code-discovery---query-the-knowledge-graph-first" does not exist in "/AGENTS.md". Fix the href or restore the target, then delete this comment. -->
1. **Use the knowledge graph** (faster than grep): See [AGENTS.md: Code Discovery](/AGENTS.md#code-discovery---query-the-knowledge-graph-first)
2. **Read subsystem specs** in [CLAUDE.md](/CLAUDE.md) (detailed architecture per crate/module)
3. **Check crate README/AGENTS files** (many crates have their own docs in `src/` or `Cargo.toml`)
@@ -215,6 +244,7 @@ When these docs don't answer your question:
## Next Steps
- **Beginner?** Start with [Development Setup](development/setup.md) and run `cargo test`
<!-- openwiki: broken internal link [development/workflows.md#code-review] heading anchor "code-review" does not exist in "development/workflows.md". Fix the href or restore the target, then delete this comment. -->
- **Reviewer?** Jump to [Workflows: Code Review](development/workflows.md#code-review)
- **Architect?** Read [Architecture Overview](architecture/overview.md) and [CLAUDE.md](/CLAUDE.md)
- **Seeking a specific feature?** Use the navigation table above or grep the docs