feat: update documentation links and add README files for core, swarm, and SDK modules

Theaxiom · Theaxiom · commit 3bf71ce81252 · 2026-03-02T21:47:57.000-08:00
diff --git a/README.md b/README.md
@@ -74,7 +74,7 @@ aegis task logs <execution-id>        # View execution logs
 aegis task cancel <execution-id>      # Cancel execution
 ```
 
-See [CLI Reference](docs/CLI_REFERENCE.md) for complete documentation.
+See [CLI Reference](https://docs.100monkeys.ai/docs/reference/cli) for complete documentation.
 
 ### Edge Node (`edge-node/`)
 
@@ -136,7 +136,7 @@ spec:
       level: "info"
 ```
 
-See [aegis-config.yaml](aegis-config.yaml) for a complete example.
+See [Node Config Reference](https://docs.100monkeys.ai/docs/reference/node-config) and [`aegis-config.yaml`](aegis-config.yaml) for a complete example.
 
 ### Debugging and Logging
 
@@ -219,7 +219,7 @@ target/debug/aegis agent logs echo
 target/debug/aegis daemon stop
 ```
 
-For detailed instructions, see [Getting Started Guide](docs/GETTING_STARTED.md).
+For detailed instructions, see [Getting Started Guide](https://docs.100monkeys.ai/docs/getting-started).
 
 ## Development
 
@@ -270,7 +270,7 @@ The orchestrator enforces:
 - **Resource Limits**: CPU, memory, execution time
 - **Audit Trail**: Immutable logging
 
-For details, see [SECURITY.md](SECURITY.md).
+For details, see [Security Model](https://docs.100monkeys.ai/docs/concepts/security-model).
 
 ## Performance
 
@@ -286,9 +286,22 @@ Full documentation is available at **[docs.100monkeys.ai](https://docs.100monkey
 | --- | --- |
 | [Getting Started](https://docs.100monkeys.ai/docs/getting-started) | Install, configure, and run your first agent |
 | [Core Concepts](https://docs.100monkeys.ai/docs/concepts) | Agents, executions, workflows, swarms, security model |
-| [Guides](https://docs.100monkeys.ai/docs/guides) | Writing agents, building workflows, configuring storage |
+| [Writing Agents](https://docs.100monkeys.ai/docs/guides/writing-agents) | Author and structure agent code |
+| [Deploying Agents](https://docs.100monkeys.ai/docs/guides/deploying-agents) | Deploy agents with the CLI or API |
+| [LLM Providers](https://docs.100monkeys.ai/docs/guides/llm-providers) | Configure Ollama, OpenAI, and other LLM backends |
+| [Building Workflows](https://docs.100monkeys.ai/docs/guides/building-workflows) | Chain agents into multi-step workflows |
+| [Building Swarms](https://docs.100monkeys.ai/docs/guides/building-swarms) | Coordinate parallel agent swarms |
+| [Configuring Storage](https://docs.100monkeys.ai/docs/guides/configuring-storage) | Persistent storage backends for agents |
+| [Local Testing](https://docs.100monkeys.ai/docs/guides/local-testing) | Test agents locally before deploying |
 | [Architecture](https://docs.100monkeys.ai/docs/architecture) | Execution engine, SMCP, storage gateway, event bus |
-| [Deployment](https://docs.100monkeys.ai/docs/deployment) | Docker, Firecracker, IAM, secrets, configuration reference |
+| [Security Model](https://docs.100monkeys.ai/docs/concepts/security-model) | Isolation, network control, secrets, audit trail |
+| [Deployment — Docker](https://docs.100monkeys.ai/docs/deployment/docker) | Run the orchestrator with Docker |
+| [Deployment — Firecracker](https://docs.100monkeys.ai/docs/deployment/firecracker) | Production micro-VM setup |
+| [Secrets Management](https://docs.100monkeys.ai/docs/deployment/secrets) | OpenBao / Vault integration (Keymaster Pattern) |
+| [IAM](https://docs.100monkeys.ai/docs/deployment/iam) | Keycloak identity and access management |
+| [Configuration Reference](https://docs.100monkeys.ai/docs/reference/node-config) | `NodeConfig` YAML reference (`aegis-config.yaml`) |
+| [Agent Manifest Reference](https://docs.100monkeys.ai/docs/reference/agent-manifest) | `AgentManifest` YAML field reference |
+| [Workflow Manifest Reference](https://docs.100monkeys.ai/docs/reference/workflow-manifest) | `WorkflowManifest` YAML field reference |
 | [CLI Reference](https://docs.100monkeys.ai/docs/reference/cli) | Complete `aegis` CLI command reference |
 | [gRPC API](https://docs.100monkeys.ai/docs/reference/grpc-api) | `aegis.runtime.v1` service methods and message types |
 
diff --git a/cli/Cargo.toml b/cli/Cargo.toml
@@ -7,6 +7,7 @@ authors.workspace = true
 license.workspace = true
 repository.workspace = true
 description = "100monkeys.ai AEGIS orchestrator CLI and daemon"
+readme = "README.md"
 
 [lib]
 name = "aegis_orchestrator"
diff --git a/cli/README.md b/cli/README.md
@@ -0,0 +1,138 @@
+# aegis-orchestrator
+
+[![Crates.io](https://img.shields.io/crates/v/aegis-orchestrator.svg)](https://crates.io/crates/aegis-orchestrator)
+[![Docs.rs](https://docs.rs/aegis-orchestrator/badge.svg)](https://docs.rs/aegis-orchestrator)
+[![License: AGPL-3.0](https://img.shields.io/badge/license-AGPL%203.0-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
+[![Documentation](https://img.shields.io/badge/docs-docs.100monkeys.ai-brightgreen.svg)](https://docs.100monkeys.ai)
+
+The `aegis` CLI and daemon binary for the [100monkeys.ai AEGIS](https://docs.100monkeys.ai) platform — a secure, serverless runtime for autonomous AI agents.
+
+## Install
+
+```bash
+cargo install aegis-orchestrator
+```
+
+Or build from source:
+
+```bash
+git clone https://github.com/100monkeys-ai/aegis-orchestrator
+cd aegis-orchestrator
+cargo build --release -p aegis-orchestrator
+```
+
+## Quick Start
+
+```bash
+# 1. Start the daemon
+aegis daemon start
+
+# 2. Deploy an agent
+aegis agent deploy agent.yaml
+
+# 3. Run a task
+aegis task execute my-agent --input "Summarise the README"
+
+# 4. Stream logs
+aegis agent logs my-agent
+
+# 5. Stop the daemon
+aegis daemon stop
+```
+
+## Command Reference
+
+### Daemon
+
+```bash
+aegis daemon start               # Start the orchestrator daemon
+aegis daemon stop                # Stop the daemon
+aegis daemon status              # Show daemon health and version
+```
+
+### Agents
+
+```bash
+aegis agent deploy agent.yaml    # Deploy an agent from a manifest
+aegis agent list                 # List all deployed agents
+aegis agent logs <name>          # Stream live agent logs
+aegis agent remove <id>          # Remove a deployed agent
+```
+
+### Tasks (Executions)
+
+```bash
+aegis task execute <agent> --input "..."   # Submit a task
+aegis task list                            # List recent executions
+aegis task logs <execution-id>             # View execution logs
+aegis task cancel <execution-id>           # Cancel a running execution
+```
+
+### Debug Logging
+
+```bash
+# Enable verbose structured logs (includes bootstrap.py stdout/stderr)
+RUST_LOG=debug aegis daemon start
+
+# Or via config (aegis-config.yaml)
+spec:
+  observability:
+    logging:
+      level: debug   # trace | debug | info | warn | error
+```
+
+## Configuration
+
+The daemon is configured via `aegis-config.yaml` in the working directory:
+
+```yaml
+apiVersion: 100monkeys.ai/v1
+kind: NodeConfig
+metadata:
+  name: my-node
+spec:
+  node:
+    id: my-node-001
+    type: edge
+  llm_providers:
+    - name: local
+      type: ollama
+      endpoint: http://localhost:11434
+      enabled: true
+      models:
+        - alias: default
+          model: phi3:mini
+          capabilities: [code, reasoning]
+  llm_selection:
+    strategy: prefer-local
+    default_provider: local
+```
+
+See the [Node Config Reference](https://docs.100monkeys.ai/docs/reference/node-config) for all fields.
+
+## Documentation
+
+| Resource | Link |
+| --- | --- |
+| Getting Started | [docs.100monkeys.ai/docs/getting-started](https://docs.100monkeys.ai/docs/getting-started) |
+| CLI Reference | [docs.100monkeys.ai/docs/reference/cli](https://docs.100monkeys.ai/docs/reference/cli) |
+| Node Config Reference | [docs.100monkeys.ai/docs/reference/node-config](https://docs.100monkeys.ai/docs/reference/node-config) |
+| Agent Manifest Reference | [docs.100monkeys.ai/docs/reference/agent-manifest](https://docs.100monkeys.ai/docs/reference/agent-manifest) |
+| Deploying Agents | [docs.100monkeys.ai/docs/guides/deploying-agents](https://docs.100monkeys.ai/docs/guides/deploying-agents) |
+| Docker Deployment | [docs.100monkeys.ai/docs/deployment/docker](https://docs.100monkeys.ai/docs/deployment/docker) |
+| Firecracker Deployment | [docs.100monkeys.ai/docs/deployment/firecracker](https://docs.100monkeys.ai/docs/deployment/firecracker) |
+| Local Testing | [docs.100monkeys.ai/docs/guides/local-testing](https://docs.100monkeys.ai/docs/guides/local-testing) |
+
+## Related Crates
+
+| Crate | Description |
+| --- | --- |
+| [`aegis-orchestrator-core`](https://crates.io/crates/aegis-orchestrator-core) | Domain logic and runtime primitives |
+| [`aegis-orchestrator-swarm`](https://crates.io/crates/aegis-orchestrator-swarm) | Swarm coordination |
+| [`aegis-orchestrator-sdk`](https://crates.io/crates/aegis-orchestrator-sdk) | Rust SDK for agent authors |
+
+## License
+
+Copyright © 2026 100monkeys AI, Inc.
+
+Licensed under the [GNU Affero General Public License v3.0](https://www.gnu.org/licenses/agpl-3.0) (AGPL-3.0).
diff --git a/orchestrator/core/Cargo.toml b/orchestrator/core/Cargo.toml
@@ -7,11 +7,13 @@ authors.workspace = true
 license.workspace = true
 repository.workspace = true
 description = "Core domain and runtime primitives for the 100monkeys.ai AEGIS orchestrator"
+readme = "README.md"
 
 # Include proto-vendor in published packages (created by CI)
 include = [
     "src/**/*.rs",
     "Cargo.toml",
+    "README.md",
     "build.rs",
     "proto-vendor/**/*.proto",
 ]
diff --git a/orchestrator/core/README.md b/orchestrator/core/README.md
@@ -0,0 +1,57 @@
+# aegis-orchestrator-core
+
+[![Crates.io](https://img.shields.io/crates/v/aegis-orchestrator-core.svg)](https://crates.io/crates/aegis-orchestrator-core)
+[![Docs.rs](https://docs.rs/aegis-orchestrator-core/badge.svg)](https://docs.rs/aegis-orchestrator-core)
+[![License: AGPL-3.0](https://img.shields.io/badge/license-AGPL%203.0-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
+[![Documentation](https://img.shields.io/badge/docs-docs.100monkeys.ai-brightgreen.svg)](https://docs.100monkeys.ai)
+
+Core domain logic and runtime primitives for the [100monkeys.ai AEGIS](https://docs.100monkeys.ai) orchestrator. This crate is the **pure domain kernel** — it has no dependency on any particular runtime, database, or HTTP framework except through trait abstractions.
+
+## What's in this crate
+
+| Layer | Contents |
+| --- | --- |
+| **Domain** | `Agent`, `Execution`, `Workflow`, `Swarm`, `SmcpSession`, `SecurityContext`, `Policy`, `NodeConfig`, `RuntimeRegistry` value objects and entities |
+| **Application** | Orchestration services: `InnerLoopService`, `LifecycleService`, `ToolInvocationService`, `ValidationService`, `StorageRouter`, `VolumeManager`, `NfsGateway` |
+| **Infrastructure** | Trait implementations for Docker runtime, LLM providers, Temporal client, Cortex/memory, gRPC (AEGIS Runtime Proto), SeaweedFS, OpenBao secrets |
+| **Presentation** | Axum HTTP handlers for the `/v1` REST API and gRPC service endpoints |
+
+## Key Concepts
+
+- **Agent** — a stateless, containerised unit of autonomous work defined by an [`AgentManifest`](https://docs.100monkeys.ai/docs/reference/agent-manifest)
+- **Execution** — a single agent invocation; lifecycle: `Pending → Running → Succeeded | Failed | Cancelled`
+- **SMCP** — Secure Model Context Protocol (ADR-035); every tool call is signed with Ed25519 and validated end-to-end
+- **Dispatch Gateway** — all tool calls route through the orchestrator proxy at `/v1/dispatch-gateway` (ADR-040); agents never call external APIs directly
+- **Security Policy** — default-deny network and filesystem policies enforced at container/VM boot time
+
+## Usage
+
+This crate is not intended for direct use by agent authors — use [`aegis-orchestrator-sdk`](https://crates.io/crates/aegis-orchestrator-sdk) instead. This crate is consumed internally by the other workspace members and may be useful for advanced integrations.
+
+```toml
+[dependencies]
+aegis-orchestrator-core = "0.4.0-pre-alpha"
+```
+
+```rust
+use aegis_orchestrator_core::domain::agent::{AgentManifest, AgentSpec};
+use aegis_orchestrator_core::domain::execution::Execution;
+```
+
+## Documentation
+
+| Resource | Link |
+| --- | --- |
+| Getting Started | [docs.100monkeys.ai/docs/getting-started](https://docs.100monkeys.ai/docs/getting-started) |
+| Architecture Overview | [docs.100monkeys.ai/docs/architecture](https://docs.100monkeys.ai/docs/architecture) |
+| Execution Engine | [docs.100monkeys.ai/docs/architecture/execution-engine](https://docs.100monkeys.ai/docs/architecture/execution-engine) |
+| SMCP | [docs.100monkeys.ai/docs/architecture/smcp](https://docs.100monkeys.ai/docs/architecture/smcp) |
+| Agent Manifest Reference | [docs.100monkeys.ai/docs/reference/agent-manifest](https://docs.100monkeys.ai/docs/reference/agent-manifest) |
+| Node Config Reference | [docs.100monkeys.ai/docs/reference/node-config](https://docs.100monkeys.ai/docs/reference/node-config) |
+| Security Model | [docs.100monkeys.ai/docs/concepts/security-model](https://docs.100monkeys.ai/docs/concepts/security-model) |
+
+## License
+
+Copyright © 2026 100monkeys AI, Inc.
+
+Licensed under the [GNU Affero General Public License v3.0](https://www.gnu.org/licenses/agpl-3.0) (AGPL-3.0).
diff --git a/orchestrator/swarm/Cargo.toml b/orchestrator/swarm/Cargo.toml
@@ -7,6 +7,7 @@ authors.workspace = true
 license.workspace = true
 repository.workspace = true
 description = "Swarm coordination for the 100monkeys.ai AEGIS orchestrator"
+readme = "README.md"
 
 [dependencies]
 tokio = { workspace = true }
diff --git a/orchestrator/swarm/README.md b/orchestrator/swarm/README.md
@@ -0,0 +1,63 @@
+# aegis-orchestrator-swarm
+
+[![Crates.io](https://img.shields.io/crates/v/aegis-orchestrator-swarm.svg)](https://crates.io/crates/aegis-orchestrator-swarm)
+[![Docs.rs](https://docs.rs/aegis-orchestrator-swarm/badge.svg)](https://docs.rs/aegis-orchestrator-swarm)
+[![License: AGPL-3.0](https://img.shields.io/badge/license-AGPL%203.0-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
+[![Documentation](https://img.shields.io/badge/docs-docs.100monkeys.ai-brightgreen.svg)](https://docs.100monkeys.ai)
+
+Swarm coordination layer for the [100monkeys.ai AEGIS](https://docs.100monkeys.ai) orchestrator. Implements the **Swarm** bounded context — parallel multi-agent orchestration with fan-out dispatch, result aggregation, and supervisor-managed lifecycles.
+
+## What's in this crate
+
+| Layer | Contents |
+| --- | --- |
+| **Domain** | `Swarm` aggregate, `SwarmSpec`, member state machine, fan-out / aggregation strategies |
+| **Application** | `SwarmService` — create, dispatch, aggregate, and resolve swarms |
+
+## Key Concepts
+
+- **Swarm** — a named group of agents that execute the same stimulus in parallel and whose results are aggregated by a configurable strategy (e.g. `first-success`, `majority-vote`, `all`)
+- **Supervisor** — an optional coordinating agent that reviews aggregated swarm output before surfacing a final result
+- Swarms compose naturally with **Workflows** — a workflow step can fan out to a swarm and collect a single resolved output
+
+```markdown
+Stimulus ──► SwarmService.dispatch()
+                │
+          ┌─────┴─────┐
+          ▼           ▼
+       Agent A     Agent B     … Agent N
+          │           │
+          └─────┬─────┘
+                ▼
+           Aggregator
+                │
+           (Supervisor)
+                │
+                ▼
+           Final Result
+```
+
+## Usage
+
+```toml
+[dependencies]
+aegis-orchestrator-swarm = "0.4.0-pre-alpha"
+```
+
+```rust
+use aegis_orchestrator_swarm::application::SwarmService;
+```
+
+## Documentation
+
+| Resource | Link |
+| --- | --- |
+| Swarms Concept | [docs.100monkeys.ai/docs/concepts/swarms](https://docs.100monkeys.ai/docs/concepts/swarms) |
+| Building Swarms Guide | [docs.100monkeys.ai/docs/guides/building-swarms](https://docs.100monkeys.ai/docs/guides/building-swarms) |
+| Architecture Overview | [docs.100monkeys.ai/docs/architecture](https://docs.100monkeys.ai/docs/architecture) |
+
+## License
+
+Copyright © 2026 100monkeys AI, Inc.
+
+Licensed under the [GNU Affero General Public License v3.0](https://www.gnu.org/licenses/agpl-3.0) (AGPL-3.0).
diff --git a/sdks/Cargo.toml b/sdks/Cargo.toml
@@ -7,6 +7,7 @@ authors.workspace = true
 license.workspace = true
 repository.workspace = true
 description = "Rust SDK for building 100monkeys.ai AEGIS agents"
+readme = "README.md"
 
 [dependencies]
 aegis-orchestrator-core = { path = "../orchestrator/core", version = "0.4.0-pre-alpha" }
diff --git a/sdks/README.md b/sdks/README.md
