154 lines
4.2 KiB
Markdown
154 lines
4.2 KiB
Markdown
|
# 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
|