# Agent Onboarding

A step-by-step checklist for an AI agent starting work in this environment. Read this before touching anything.

---

## Step 1 — Orient Yourself

Read these files in order:

1. **`AGENTS.md`** — rules for working in this repo (what goes where, what not to do)
2. **`README.md`** — environment at a glance, structure overview
3. **`manifest.json`** — full machine-readable index

If you're here for a specific client or project, also read:
- `clients/<client>.md` — for client work
- `projects/<project>.md` — for internal work

---

## Step 2 — Verify Network Access

```bash
# Are you on Tailscale?
tailscale status

# Can you reach Gitea?
curl -s http://100.79.253.19:3000/api/v1/version
# Expected: {"version":"1.26.2"}

# Can you reach AWS?
aws sts get-caller-identity
# Expected: account 567637986724, user jacob_mathison
```

If Tailscale is not connected, cross-machine operations and Gitea access will fail.
If AWS fails, check that `~/.aws/credentials` has the `default` profile set.

---

## Step 3 — Know Your Machine

You are most likely running on one of these:

| Machine | Tailscale IP | Where am I? |
|---------|-------------|-------------|
| **Tabitha** | `100.76.192.116` | Silma's primary — OpenClaw, k8s, full toolchain |
| **Orson** | `100.79.253.19` | Gitea host, CI runner |
| **Ozymandias** | `100.115.222.5` | Travel/coding box |
| **Hunter's machine** | `creon.ngrok.app` | Remote via Creon tunnel |

```bash
hostname && tailscale ip
```

Full machine details: [`documents/machines.md`](./machines.md)

---

## Step 4 — Find the Code

### Local Gitea (private repos)
```bash
# List available repos
curl -s -u jacob-mathison:<PAT> http://100.79.253.19:3000/api/v1/repos/search \
  | python3 -c "import sys,json; [print(r['full_name']) for r in json.load(sys.stdin)['data']]"

# Clone a repo
git clone http://100.79.253.19:3000/jacob-mathison/<repo-name>.git
```

Generate a PAT at: `http://100.79.253.19:3000/user/settings/applications`

### GitHub (public + silmaai private repos)
```bash
source /Users/Tabitha/.openclaw/workspace/credentials/secrets.env
git clone https://$GITHUB_PAT@github.com/silmaai/<repo>.git
git clone https://github.com/MathisonProjects/<repo>.git
```

Full details: [`tools/gitea.llm.md`](../tools/gitea.llm.md) · [`tools/github.llm.md`](../tools/github.llm.md)

---

## Step 5 — Check If You Need k8s Services (Tabitha only)

If working on anything that uses Postgres, Redis, Qdrant, Vault, or Temporal:

```bash
# Is Docker Desktop running?
docker ps

# Start port-forward (run in a separate terminal, stays in foreground)
bash /Users/Tabitha/.openclaw/k8s/silma-ai/scripts/port-forward.sh

# Verify Vault is up
curl -s http://localhost:18200/v1/sys/health | python3 -m json.tool

# Is Hagia mounted? (k8s PVCs depend on it)
ls /Volumes/Hagia/k8s/volumes/
```

Full details: [`tools/k8s.llm.md`](../tools/k8s.llm.md) · [`tools/vault.llm.md`](../tools/vault.llm.md)

---

## Step 6 — Check AWS Access (if relevant)

```bash
# Verify identity
aws sts get-caller-identity

# Quick sanity check — list S3 buckets
aws s3 ls | head -5
```

Full details: [`tools/aws-cli.llm.md`](../tools/aws-cli.llm.md)

---

## Step 7 — Read Agent-Specific Notes

Check `agents/<your-agent>.md` for any config or instructions specific to the tool you're running in.

| You are | Read |
|---------|------|
| Claude / Claude Code | [`agents/claude.md`](../agents/claude.md) |
| Cursor | [`agents/cursor.md`](../agents/cursor.md) |
| Codex | [`agents/codex.md`](../agents/codex.md) |

---

## Quick Reference Card

```
Gitea:       http://100.79.253.19:3000     (PAT auth, Tailscale required)
GitHub PAT:  $GITHUB_PAT in credentials/secrets.env
AWS:         account 567637986724, us-east-1, profile=default
Vault:       http://localhost:18200  token=devroot  (k8s port-forward required)
k8s:         context=docker-desktop  namespace=silma-ai
Workspace:   /Users/Tabitha/.openclaw/workspace/
Father repos:/Volumes/Hagia/workspaces/workspace_Father/
```

---

## Red Lines

- Do not commit secrets or tokens to any repo
- Do not push private client code to GitHub — use Gitea
- Do not run destructive AWS operations (`s3 rb`, `amplify delete`, etc.) without confirming
- Do not delete k8s PVCs — they hold persistent data
- Prefer `--dry-run` when unsure