# AI Core — SnS Network Solutions

The holding company's internal AI team. A **strict hierarchy**: one leader agent
(**Chief**) is the single point of contact and routes work to a lean set of
specialists. Nothing runs unless it's necessary to the business.

> **Goal:** all services eventually run on AWS (EC2 + Bedrock). **For now** it runs on
> the home server `ws` in a VM. The stack is containerized so it moves between the two
> **unchanged** — the VM is disposable; this git folder is the source of truth.

## Chain of command

```
        SAM  (owner / CEO — final authority, approval gates)
         │   you talk to ONE agent
        CHIEF  (team leader — routes, decides, aggregates, enforces gates)
         │   specialists report UP only, never to each other
   ┌─────┼─────┐
 SCOUT  SCRIBE  (LEDGER — add when billing starts)
research  docs
```

- You only ever message **Chief**. Specialists have no direct channel to you.
- Specialists only talk to **Chief** — no lateral messaging (enforced by config).
- Chief cannot send external comms, move money, or make legal promises — those
  escalate back to you. Chief runs the team; you stay CEO.

## Roster (lean — only what the business needs now)

| Agent | Role | Status |
|-------|------|--------|
| **Chief** | Team leader / orchestrator. Single point of contact, routing, aggregation, approval gates. | Active |
| **Scout** | Research & competitive intel. Read-only, informational. | Active |
| **Scribe** | Documents — proposals, SOWs, NDAs, SOPs — from templates, held for review. | Active |
| Ledger | Bookkeeping/billing prep. Generates, never sends or pays. | Add when invoicing starts |

Add specialists *under* Chief as the business creates work for them. The command
structure never changes — that's the point.

## Layout

```
ai-core/
├── docker-compose.yml     OpenClaw gateway (image ghcr.io/openclaw/openclaw, :18789)
├── .env.example           config template — copy to .env, fill in, never commit .env
├── .gitignore
├── agents/                canonical agent definitions (version-controlled)
│   ├── chief/             team leader
│   ├── scout/             research specialist
│   └── scribe/            document & visual specialist
│       each agent folder holds its OpenClaw workspace:
│         SOUL · IDENTITY · USER · AGENTS · TOOLS · HEARTBEAT · MEMORY
│         + skills/   knowledge/   projects/
├── knowledge/             shared knowledge base — sns.md (brand foundation) + research/reference docs
└── state/                 runtime state + sessions (gitignored, created on first run)
```

## Run it (on the `ws` VM)

Prereqs: a Linux VM with Docker + Docker Compose, and ≥4GB RAM (OpenClaw OOMs under 2GB).

```bash
cp .env.example .env        # then fill in your OpenAI API key + model refs
docker compose up -d
docker compose logs -f gateway
```

The gateway binds to `127.0.0.1:18789` only — it is **not** exposed to the internet.
Reach the web UI over Tailscale or an SSH tunnel:

```bash
ssh -L 18789:127.0.0.1:18789 <user>@ws   # then open http://localhost:18789
```

**Register the agents** (first run) — the canonical SOUL.md files live in `agents/`;
register each with the gateway so it picks them up:

```bash
docker compose exec gateway openclaw agents add chief
docker compose exec gateway openclaw agents add scout
docker compose exec gateway openclaw agents add scribe
docker compose exec gateway openclaw agents list --bindings
```

> ponytail: exact `agents add` workflow + workspace path (`~/.openclaw/agents/<id>/workspace/SOUL.md`)
> should be confirmed against https://docs.openclaw.ai on first run — ceiling: this is a
> one-time manual registration step, not yet automated. Upgrade path: a bootstrap script
> that syncs `agents/*/SOUL.md` into the state volume on `up`.

## LLM backend — OpenAI / ChatGPT (current)

OpenClaw talks to OpenAI via an **API key**.

- **On `ws` now:** put your `OPENAI_API_KEY` in `.env` (see `.env.example`) and set the
  model refs. Route routine work to a small/fast model and reasoning to a strong one to
  control cost.
- The key is the only credential needed — no cloud account required to run on `ws`.

## Move to AWS + Bedrock (future goal)

The end goal is to run this same stack on AWS with Amazon Bedrock. When we migrate, run the
*same* `docker compose up` on an EC2 instance (t3.large, 8GB): drop the `OPENAI_*` keys,
attach an **IAM instance role** so OpenClaw uses Bedrock via the AWS credential chain, put a
Bedrock VPC endpoint in front, and reach the gateway over Tailscale/SSM. **The agents,
skills, and compose file are identical** — only the provider config changes. That backend
portability is the whole point of this design.
