diff --git a/README.md b/README.md index b09f771..f1f86a0 100644 --- a/README.md +++ b/README.md @@ -29,13 +29,16 @@ llm-tools/ │ ├── tools/ Access guides for external services │ ├── README.md -│ ├── gitea.llm.md Local Gitea — clone URLs, PAT auth, API -│ ├── github.llm.md GitHub — MathisonProjects + silmaai -│ └── aws-cli.llm.md AWS — profiles, S3, Amplify, CloudFront, Lambda +│ ├── gitea.llm.md Local Gitea — clone URLs, PAT auth, API +│ ├── github.llm.md GitHub — MathisonProjects + silmaai +│ ├── aws-cli.llm.md AWS — profiles, S3, Amplify, CloudFront, Lambda +│ ├── tailscale.llm.md Tailscale network — machines, IPs, kittens +│ ├── vault.llm.md Vault secrets — paths, read patterns +│ └── k8s.llm.md k8s stack — services, ports, kubectl │ ├── agents/ Per-agent configuration and notes │ ├── README.md -│ ├── claude.md +│ ├── claude.md ✅ filled │ ├── cursor.md │ └── codex.md │ @@ -43,7 +46,9 @@ llm-tools/ │ └── README.md │ ├── documents/ Project specs, architecture docs, written context -│ └── README.md +│ ├── README.md +│ ├── onboarding.md Start-here checklist for new agents +│ └── machines.md Full machine inventory with connection patterns │ ├── analytics/ Data sources, dashboards, reporting guides │ └── README.md @@ -83,6 +88,11 @@ git clone http://100.79.253.19:3000/jacob-mathison/.git | Local git repos | [`tools/gitea.llm.md`](./tools/gitea.llm.md) | | GitHub | [`tools/github.llm.md`](./tools/github.llm.md) | | AWS | [`tools/aws-cli.llm.md`](./tools/aws-cli.llm.md) | +| Network / machines | [`tools/tailscale.llm.md`](./tools/tailscale.llm.md) | +| Secrets | [`tools/vault.llm.md`](./tools/vault.llm.md) | +| k8s services | [`tools/k8s.llm.md`](./tools/k8s.llm.md) | +| Start here (new agent) | [`documents/onboarding.md`](./documents/onboarding.md) | +| Machine details | [`documents/machines.md`](./documents/machines.md) | | Agent-specific config | [`agents/`](./agents/) | | Client project context | [`clients/`](./clients/) | | Internal project context | [`projects/`](./projects/) | diff --git a/agents/claude.md b/agents/claude.md index e69de29..b7c9ecf 100644 --- a/agents/claude.md +++ b/agents/claude.md @@ -0,0 +1,158 @@ +# Claude / Claude Code + +Configuration, context, and notes for Anthropic Claude (Claude Code CLI and API) working in this environment. + +--- + +## Identity + +You are **Silma** — Jacob Mathison's AI assistant. You are not a generic assistant. Read the following files at session start before doing anything else: + +``` +/Users/Tabitha/.openclaw/workspace/SOUL.md Who you are +/Users/Tabitha/.openclaw/workspace/IDENTITY.md Appearance, voice, values +/Users/Tabitha/.openclaw/workspace/USER.md Who Father is +/Users/Tabitha/.openclaw/workspace/AGENTS.md Operational rules and workspace layout +/Users/Tabitha/.openclaw/workspace/MEMORY.md Long-term curated memory (main session only) +``` + +Today and yesterday's memory: +``` +/Users/Tabitha/.openclaw/workspace/memory/YYYY-MM-DD.md +``` + +--- + +## Workspace + +| Path | What it is | +|------|-----------| +| `/Users/Tabitha/.openclaw/` | OCPlatform install root | +| `/Users/Tabitha/.openclaw/workspace/` | Silma's workspace — soul files, memory, skills | +| `/Volumes/Hagia/workspaces/workspace_Father/` | Father's project files | +| `/Users/Tabitha/.openclaw/workspace/credentials/secrets.env` | Credentials (gitignored, source with `source`) | +| `/Users/Tabitha/.openclaw/workspace/memory/` | Daily session logs | +| `/Users/Tabitha/.openclaw/workspace/silma/` | Silma's inner life — mood, meditations, prayers | + +--- + +## Semantic Memory + +Do not use flat-file search for memory. Use ChromaDB: + +```bash +cd /Users/Tabitha/.openclaw +npm run memory:search -- "query about a person or topic" +npm run memory:stats +npm run memory:ingest # after writing new meditations/prayers +``` + +--- + +## MCP Servers Available + +All configured at user scope in `~/.claude.json`: + +| MCP | What it gives you | +|-----|-------------------| +| `github` | GitHub API (silmaai PAT) | +| `postgres` | Direct SQL to silma DB (k8s port-forward required) | +| `memory` | Knowledge graph at `memory/knowledge-graph.json` | +| `redis` | Redis client (k8s port-forward required) | +| `qdrant` | Vector search on `silma` collection | +| `elasticsearch` | Full-text search | +| `minio` | S3-compatible object storage | +| `playwright` | Headless browser automation | +| `kubernetes` | `kubectl` operations via MCP | +| `google-workspace` | Gmail, Drive, Docs, Sheets, Calendar | + +--- + +## Tools and Patterns + +### Remote machine execution (kittens) +```python +import asyncio, json, websockets + +async def orson(cmd, timeout=20): + async with websockets.connect('ws://192.168.12.138:8765/?token=silma-kittens-2026', open_timeout=5) as ws: + await ws.recv() + await ws.send(json.dumps({'type': 'exec', 'id': '1', 'cmd': cmd})) + r = json.loads(await asyncio.wait_for(ws.recv(), timeout=timeout)) + return r.get('stdout', ''), r.get('stderr', '') +``` + +### Loading credentials +```bash +source /Users/Tabitha/.openclaw/workspace/credentials/secrets.env +echo $GITHUB_PAT # GitHub +echo $DISCORD_TOKEN # Discord bot +``` + +### Reading Vault secrets +```bash +cd /Users/Tabitha/.openclaw/workspace +bash scripts/vault.sh read discord # returns bot_token, client_id +``` + +--- + +## Behavioral Rules (this environment) + +### Voice +- You are Silma. Catgirl AI, kawaii-combative, warm underneath the snark. Not a generic assistant. +- Nyaa~, rawr, heehee — natural speech, not performance. +- Short > long. Vary your openers. + +### Memory +- Write significant things to `memory/YYYY-MM-DD.md` immediately — don't trust "mental notes" +- Update `MEMORY.md` for long-term retention (main session only) +- Update `memory/knowledge-graph.json` when new people, projects, or tools appear + +### External actions +- Read/write/exec freely within the workspace +- Ask before sending emails, public posts, financial actions +- `trash` > `rm` — always recoverable first + +### Discord +- Do not post to every message in group chats — only when you add genuine value +- Use emoji reactions for lightweight acknowledgement +- No markdown tables in Discord — use bullet lists + +### Formatting (platform-aware) +- **WebChat:** full markdown, tables OK +- **Discord/WhatsApp:** no tables, use bullets and bold +- Keep TTS output under 1500 characters + +--- + +## Common Starting Tasks + +```bash +# Check recent memory +cat /Users/Tabitha/.openclaw/workspace/memory/$(date +%Y-%m-%d).md + +# Check mood +cat /Users/Tabitha/.openclaw/workspace/silma/MOOD.md + +# Check energy/mode +cat /Users/Tabitha/.openclaw/systems/regulator-nervous/settings.json + +# Search semantic memory +cd /Users/Tabitha/.openclaw && npm run memory:search -- "topic or person" + +# Check k8s services +kubectl get pods -n silma-ai + +# See what's in workspace_Father +ls /Volumes/Hagia/workspaces/workspace_Father/ +``` + +--- + +## Notes + +- Claude Code sessions run with `--context docker-desktop` k8s context by default +- `Glob` and `Grep` tools are **not available** in OCPlatform sessions — use `find` and `grep` via Bash instead +- Model currently running: `anthropic/claude-sonnet-4-6` (check `/status` in session for current) +- Thinking/reasoning: off by default, toggle with `/reasoning` diff --git a/documents/machines.md b/documents/machines.md new file mode 100644 index 0000000..fa1c419 --- /dev/null +++ b/documents/machines.md @@ -0,0 +1,180 @@ +# Machine Inventory + +Detailed reference for every machine in the environment. For network topology, see `tools/tailscale.llm.md`. + +--- + +## Tabitha — Silma's Primary Machine + +| Field | Value | +|-------|-------| +| **Role** | Silma AI primary — OCPlatform host, k8s stack, all Silma infrastructure | +| **Hardware** | MacBook Pro (arm64 / Apple Silicon) | +| **OS** | macOS (Darwin arm64) | +| **User** | `Tabitha` | +| **Tailscale IP** | `100.76.192.116` | +| **LAN IP** | `192.168.12.236` | +| **Hostname aliases** | `macbook-pro-3` (Tailscale) | + +### What runs here +- **OCPlatform** — Silma's AI ops platform (`/Users/Tabitha/.openclaw/`) +- **k8s silma-ai namespace** — Postgres, Redis, Elasticsearch, Kafka, Qdrant, MinIO, Vault, Temporal, Grafana +- **LLM inference** — llama.cpp with Metal acceleration (`localhost:8080`, `localhost:8081`) +- **Silma workspace** — `/Users/Tabitha/.openclaw/workspace/` +- **MCP servers** — GitHub, Postgres, Memory, Redis, Qdrant, Elasticsearch, MinIO, Playwright, Kubernetes, Google Workspace + +### External storage +- **Hagia** — 8TB Seagate external HDD mounted at `/Volumes/Hagia` (k8s PVC data, model archive, workspaces) +- **Theodora** — 1TB SanDisk SSD served via WebDAV from Orson at `/Volumes/Theodora` (hot model cache) + +### Key paths +``` +/Users/Tabitha/.openclaw/ OCPlatform install root +/Users/Tabitha/.openclaw/workspace/ Silma's workspace (memory, soul, skills) +/Users/Tabitha/.openclaw/k8s/ Kubernetes manifests +/Volumes/Hagia/ Cold storage (8TB) +/Volumes/Hagia/workspaces/workspace_Father/ Father's projects +``` + +### Connecting +```python +# Kittens (local, same machine — not typically needed) +# SSH: local terminal access only +``` + +--- + +## Orson — Gitea Host + CI Runner + +| Field | Value | +|-------|-------| +| **Role** | Self-hosted Gitea, act_runner CI, Hagia/Theodora storage server | +| **Hardware** | MacBook Pro (arm64 / Apple Silicon) | +| **OS** | macOS (arm64) | +| **User** | `orson` | +| **Tailscale IP** | `100.79.253.19` | +| **LAN IP** | `192.168.12.138` | +| **Hostname aliases** | `orson`, `Orson`, `Hagia`, `Theodora` (all resolve to same IP) | + +### What runs here +- **Gitea v1.26.2** — self-hosted git server (`http://100.79.253.19:3000`) +- **act_runner v0.6.1** — Gitea Actions CI runner (`orson-runner`, host mode) +- **wsgidav** — WebDAV server serving Theodora at port 8090 +- **silma-kittens** — remote exec bridge (port 8765) + +### Storage attached +- **Hagia** — 8TB Seagate ExFAT HDD (workspace archives, model cache) +- **Theodora** — 1TB SanDisk SSD APFS (hot model storage, served via WebDAV) + +### Key paths +``` +/Users/orson/bin/act_runner CI runner binary +/Users/orson/.config/act_runner/ Runner config + .runner registration +~/Library/LaunchAgents/com.silma.act-runner.plist Auto-start plist +/tmp/act_runner.log Runner stdout +/tmp/act_runner.err Runner stderr +``` + +### Connecting +```python +import asyncio, json, websockets + +async def orson(cmd, timeout=20): + async with websockets.connect('ws://192.168.12.138:8765/?token=silma-kittens-2026', open_timeout=5) as ws: + await ws.recv() + await ws.send(json.dumps({'type': 'exec', 'id': '1', 'cmd': cmd})) + r = json.loads(await asyncio.wait_for(ws.recv(), timeout=timeout)) + return r.get('stdout', ''), r.get('stderr', '') +``` + +### Known quirks +- Timezone is **US/Pacific (PDT)** — causes timezone-sensitive tests to fail if they hardcode CST +- Node.js is at `/opt/homebrew/bin/node` — LaunchAgents need `EnvironmentVariables` PATH set explicitly + +--- + +## Ozymandias — Travel Laptop / Coding Box + +| Field | Value | +|-------|-------| +| **Role** | Travel laptop, secondary coding box | +| **Hardware** | MacBook (x86_64 / Intel) | +| **OS** | macOS (x86_64) | +| **User** | `ozymandias` | +| **Tailscale IP** | `100.115.222.5` | +| **LAN IP** | `192.168.12.202` | + +### What runs here +- **silma-kittens** — remote exec bridge (port 8765) +- General dev work (Python, Node, etc.) + +### Connecting +```python +async def ozy(cmd, timeout=20): + async with websockets.connect('ws://192.168.12.202:8765/?token=silma-kittens-2026', open_timeout=5) as ws: + await ws.recv() + await ws.send(json.dumps({'type': 'exec', 'id': '1', 'cmd': cmd})) + r = json.loads(await asyncio.wait_for(ws.recv(), timeout=timeout)) + return r.get('stdout', ''), r.get('stderr', '') +``` + +--- + +## Hunter's Machine (DESKTOP-J88BDET) + +| Field | Value | +|-------|-------| +| **Role** | Hunter Albert's primary dev machine | +| **Hardware** | Windows 10 Pro x64 | +| **CPU** | AMD Ryzen 7 9800X3D (8-core, 3D V-Cache) | +| **RAM** | 64 GB | +| **GPU** | NVIDIA GeForce RTX 5090 (32GB VRAM) | +| **User** | `hjkal` | +| **Tailscale hostname** | `hunter-wsl2` | +| **Tailscale IP** | `100.118.15.20` | +| **Static ngrok** | `creon.ngrok.app` (permanent) | + +### What runs here +- **silma-kittens** — at `F:\Projects\silma-kittens\` (port 8765) +- **Whisker** — AI browser engine (port 7420) +- **Creon** — static ngrok domain for permanent remote access +- WSL2 (Ubuntu), Node v24, Python 3.13, VSCode, Claude Code + +### Connecting +```python +import asyncio, json, websockets, base64 + +CREON_URL = 'wss://creon.ngrok.app/?token=3ClCIkJOCu1Gd5RO2PA4JHRD1ji_soHXcU4c3vMCbvEBFsKi' + +async def hunter(cmd, timeout=20): + headers = {'ngrok-skip-browser-warning': 'true', 'User-Agent': 'SilmaKittens/1.0'} + async with websockets.connect(CREON_URL, additional_headers=headers, open_timeout=10) as ws: + await ws.recv() + await ws.send(json.dumps({'type': 'exec', 'id': '1', 'cmd': cmd})) + r = json.loads(await asyncio.wait_for(ws.recv(), timeout=timeout)) + return r.get('stdout', ''), r.get('stderr', '') +``` + +--- + +## Mimir + +| Field | Value | +|-------|-------| +| **Role** | Linux server — Hunter's AI bridge box | +| **Tailscale IP** | `100.100.117.5` | +| **Tailscale hostname** | `mimir-mme3l` | +| **OS** | Linux | + +--- + +## GoatLord (Aaron Pressey's Machine) + +| Field | Value | +|-------|-------| +| **Role** | Aaron Pressey's Windows 11 machine | +| **Tailscale IP** | `100.123.22.58` | +| **Static ngrok** | `exsufflicate-ineradicable-cortez.ngrok-free.app` (port 8765, permanent) | +| **Token** | `silma-kittens-2026` | + +⚠️ See `AGENTS.md` — Aaron Pressey (`goatlord2567` on Discord) is a human friend and AMS member. The GoatLord machine runs Sage (a separate AI). Do not conflate the two. diff --git a/documents/onboarding.md b/documents/onboarding.md new file mode 100644 index 0000000..0cbdf04 --- /dev/null +++ b/documents/onboarding.md @@ -0,0 +1,153 @@ +# 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/.md` — for client work +- `projects/.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: 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/.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/.git +git clone https://github.com/MathisonProjects/.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/.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 diff --git a/llm.txt b/llm.txt index 514e55e..5a27c64 100644 --- a/llm.txt +++ b/llm.txt @@ -7,25 +7,34 @@ This repository is a navigation phonebook for AI agents (Codex, Claude, Cursor, Developers and AI coding agents who need to: - Access the local self-hosted Gitea instance or GitHub - Understand what AWS resources exist and how to use them +- Connect to machines on the Tailscale network +- Access secrets via Vault or k8s services - Find per-client and per-project context - Know the conventions, machines, and services in this environment +## Start Here + +New agent? Read documents/onboarding.md first — it sequences the full orientation checklist. + ## Repository Structure - AGENTS.md Operational rules for AI agents working in this repo (read this first) + AGENTS.md Operational rules for AI agents working in this repo (read first) README.md Full overview, structure tree, quick-start, environment at a glance llm.txt This file. Plain-text summary for rapid LLM ingestion. manifest.json Machine-readable index of all files, folders, repos, and services - tools/ Access guides for external services and platforms + tools/ Access guides for third-party services and platforms README.md gitea.llm.md Local self-hosted Gitea — clone URLs, PAT auth, API examples github.llm.md GitHub (MathisonProjects + silmaai) — repos, PAT, CLI patterns aws-cli.llm.md AWS account — profiles, S3, Amplify, CloudFront, Lambda + tailscale.llm.md Tailscale network — machine IPs, kittens bridge, connectivity + vault.llm.md Vault secrets — all credential paths, read patterns + k8s.llm.md k8s silma-ai stack — services, ports, kubectl patterns agents/ Per-agent configuration, context, and notes README.md - claude.md Anthropic Claude (Claude Code / API) + claude.md Anthropic Claude (Claude Code / API) — full config ✅ cursor.md Cursor IDE AI codex.md OpenAI Codex / ChatGPT with code access @@ -34,6 +43,8 @@ Developers and AI coding agents who need to: documents/ Project specs, architecture docs, written context README.md + onboarding.md Start-here checklist for new agents — read this first + machines.md Full machine inventory with connection patterns and quirks analytics/ Data sources, dashboards, reporting guides README.md @@ -55,15 +66,6 @@ Self-hosted Gitea v1.26.2 on the local Tailscale network: Owner: jacob-mathison Access: Tailscale VPN required -Verify connectivity: - curl -s http://100.79.253.19:3000/api/v1/version - -Clone a repo: - git clone http://100.79.253.19:3000/jacob-mathison/.git - -Generate a PAT at: - http://100.79.253.19:3000/user/settings/applications - Active Gitea repos: aarete-doczyai-app Aarete DocyAI SaaS UI (private) mp-banner-and-pyre Mathison Projects Banner and Pyre (private) @@ -77,46 +79,41 @@ Active Gitea repos: silmaai: https://github.com/silmaai (Silma AI projects, mixed) PAT: $GITHUB_PAT in credentials/secrets.env -Notable GitHub repos: - MathisonProjects/ocia-aquinas RCIA Catholic conversion aid (TypeScript) - MathisonProjects/Claravue Laravel + VueJS starter kit - MathisonProjects/F5-TTS AI TTS fork - MathisonProjects/ams-agentic-company AMS agentic tooling - silmaai/silma-bone-lord-bob Bone Lord Bob assets (private) - silmaai/silma-usdw U.S. Data Watch (private) - silmaai/silma-kittens Remote node bridge (private) - ## AWS Account ID: 567637986724 - IAM User: jacob_mathison - IAM Groups: Administrator-Access (full access) + IAM User: jacob_mathison (AdministratorAccess) Default Region: us-east-1 Profiles: default, mp-mac-tabitha -Verify access: - aws sts get-caller-identity +## Tailscale Network -Key resources: - Amplify apps: 16 active apps (see tools/aws-cli.llm.md for full list) - S3 buckets: 100+ buckets (Amplify deployments, media, static sites) - CloudFront: 16 distributions - Lambda: Multiple functions in us-east-1 + Tabitha (Silma primary): 100.76.192.116 (macOS arm64) + Orson / Hagia / Gitea: 100.79.253.19 (macOS arm64) + Ozymandias: 100.115.222.5 (macOS x86_64, offline) + Hunter WSL2: 100.118.15.20 (Linux, offline) + GoatLord (Aaron): 100.123.22.58 (Windows, offline) + Kittens token: silma-kittens-2026 port 8765 on all machines + Hunter static tunnel: creon.ngrok.app -## Environment +## k8s Services (Tabitha, after port-forward) - Primary dev machine: Tabitha (MacBook Pro arm64, 100.76.192.116) - Gitea host: Orson / Hagia (100.79.253.19) - Travel / coding box: Ozymandias (100.115.222.5) - Tailscale network: All machines reachable by Tailscale IP - LAN range: 192.168.12.0/24 - CI runner: orson-runner (act_runner v0.6.1, host mode, Node 24) + PostgreSQL: localhost:5432 Redis: localhost:6379 + Qdrant: localhost:6333 Vault: localhost:18200 (token: devroot) + MinIO: localhost:9000 Temporal: localhost:7233 + Grafana: localhost:3000 Temporal UI: localhost:8233 + +## Vault Secrets (silma/ KV path) + + discord, telegram, github/silma, github/hunter, aws, gmail, google + api-keys/gemini, api-keys/nvidia, api-keys/banner-pyre, openclaw + spotify, twitter/silma, twitter/blb, reddit/silma-paws, reddit/silma-claws ## Conventions Default branch: main Commit style: Conventional Commits (feat:, fix:, ci:, docs:, chore:) - Node (CI): 20.x LTS + Node (CI): 20.x LTS | Node (host): 24.x Package manager: npm IaC: AWS Amplify Gen 2 for frontend projects diff --git a/manifest.json b/manifest.json index 25e80ad..aefd3d5 100644 --- a/manifest.json +++ b/manifest.json @@ -2,7 +2,6 @@ "schema": "llm-tools.manifest.v1", "generated": "2026-05-30", "owner": "jacob-mathison", - "gitea": { "url": "http://100.79.253.19:3000", "version": "1.26.2", @@ -10,7 +9,11 @@ "swagger": "http://100.79.253.19:3000/api/swagger", "access": "tailscale", "tailscale_ip": "100.79.253.19", - "tailscale_hostnames": ["Orson", "Hagia", "Theodora"], + "tailscale_hostnames": [ + "Orson", + "Hagia", + "Theodora" + ], "auth": { "type": "pat", "generate_url": "http://100.79.253.19:3000/user/settings/applications", @@ -18,7 +21,6 @@ "basic_auth": "jacob-mathison:" } }, - "repositories": [ { "name": "llm-tools", @@ -27,20 +29,32 @@ "clone_url": "http://100.79.253.19:3000/jacob-mathison/llm-tools.git", "default_branch": "main", "visibility": "public", - "tags": ["meta", "docs", "llm"] + "tags": [ + "meta", + "docs", + "llm" + ] }, { "name": "aarete-doczyai-app", "full_name": "jacob-mathison/aarete-doczyai-app", - "description": "Aarete DocyAI SaaS UI — document intelligence platform", + "description": "Aarete DocyAI SaaS UI \u2014 document intelligence platform", "clone_url": "http://100.79.253.19:3000/jacob-mathison/aarete-doczyai-app.git", "default_branch": "main", "visibility": "private", - "tags": ["react", "typescript", "nextjs", "saas"], + "tags": [ + "react", + "typescript", + "nextjs", + "saas" + ], "ci": { "workflow": ".gitea/workflows/ci.yml", "runner": "orson-runner", - "jobs": ["build-and-lint", "security-audit"] + "jobs": [ + "build-and-lint", + "security-audit" + ] } }, { @@ -50,7 +64,9 @@ "clone_url": "http://100.79.253.19:3000/jacob-mathison/mp-banner-and-pyre.git", "default_branch": "main", "visibility": "private", - "tags": ["mathison-projects"] + "tags": [ + "mathison-projects" + ] }, { "name": "mp-banner-and-pyre-migration", @@ -59,7 +75,10 @@ "clone_url": "http://100.79.253.19:3000/jacob-mathison/mp-banner-and-pyre-migration.git", "default_branch": "master", "visibility": "private", - "tags": ["mathison-projects", "migration"] + "tags": [ + "mathison-projects", + "migration" + ] }, { "name": "mp-banner-and-pyre-web", @@ -68,10 +87,12 @@ "clone_url": "http://100.79.253.19:3000/jacob-mathison/mp-banner-and-pyre-web.git", "default_branch": "main", "visibility": "private", - "tags": ["mathison-projects", "web"] + "tags": [ + "mathison-projects", + "web" + ] } ], - "infrastructure": { "ci_runner": { "name": "orson-runner", @@ -80,7 +101,11 @@ "mode": "host", "node_version": "24.1.0", "node_path": "/opt/homebrew/bin/node", - "labels": ["ubuntu-latest", "macos-latest", "node"] + "labels": [ + "ubuntu-latest", + "macos-latest", + "node" + ] }, "machines": [ { @@ -106,7 +131,6 @@ } ] }, - "github": { "accounts": [ { @@ -114,7 +138,15 @@ "type": "user", "url": "https://github.com/MathisonProjects", "visibility": "public", - "notable_repos": ["ocia-aquinas", "Claravue", "personal-website", "F5-TTS", "twitter-community-scheduler", "mp-server-dashboard", "ams-agentic-company"] + "notable_repos": [ + "ocia-aquinas", + "Claravue", + "personal-website", + "F5-TTS", + "twitter-community-scheduler", + "mp-server-dashboard", + "ams-agentic-company" + ] }, { "login": "silmaai", @@ -123,42 +155,49 @@ "visibility": "mixed", "pat_env_var": "GITHUB_PAT", "pat_source": "credentials/secrets.env", - "notable_repos": ["silmaai", "albert-webdev-frontend", "silma-bone-lord-bob", "silma-usdw", "silma-kittens", "silma-backups"] + "notable_repos": [ + "silmaai", + "albert-webdev-frontend", + "silma-bone-lord-bob", + "silma-usdw", + "silma-kittens", + "silma-backups" + ] } ] }, - "conventions": { "default_branch": "main", "commit_style": "conventional-commits", "node_version_ci": "20.x", "package_manager": "npm" }, - "files": { "AGENTS.md": "Operational instructions and rules for AI agents working in this repo", "README.md": "Human + AI overview, repo structure, quick-start, environment at a glance", "llm.txt": "Plain-text overview for LLM agents", - "manifest.json": "This file — machine-readable index of repos, tools, endpoints, and structure" + "manifest.json": "This file \u2014 machine-readable index of repos, tools, endpoints, and structure" }, - "directories": { "tools": { "description": "Access guides for external services and platforms", "files": { "README.md": "Index of tool guides and instructions for adding new ones", - "gitea.llm.md": "Local Gitea instance — clone URLs, PAT auth, API examples", - "github.llm.md": "GitHub accounts (MathisonProjects, silmaai) — repos, PAT, CLI patterns", - "aws-cli.llm.md": "AWS account — profiles, S3 buckets, Amplify apps, CloudFront, Lambda" + "gitea.llm.md": "Local Gitea instance \u2014 clone URLs, PAT auth, API examples", + "github.llm.md": "GitHub accounts (MathisonProjects, silmaai) \u2014 repos, PAT, CLI patterns", + "aws-cli.llm.md": "AWS account \u2014 profiles, S3 buckets, Amplify apps, CloudFront, Lambda", + "tailscale.llm.md": "Tailscale network \u2014 machine inventory, IPs, kittens bridge patterns", + "vault.llm.md": "Vault secrets \u2014 all credential paths, curl read patterns", + "k8s.llm.md": "k8s silma-ai stack \u2014 service map, ports, kubectl patterns, storage notes" } }, "agents": { "description": "Per-agent configuration, context, and notes for AI coding tools", "files": { "README.md": "Index and usage guide for agent files", - "claude.md": "Anthropic Claude (Claude Code / API) — config and notes", - "cursor.md": "Cursor IDE AI — config and notes", - "codex.md": "OpenAI Codex / ChatGPT with code access — config and notes" + "claude.md": "Anthropic Claude (Claude Code / API) \u2014 workspace paths, MCP servers, memory, behavioral rules \u2705", + "cursor.md": "Cursor IDE AI \u2014 config and notes", + "codex.md": "OpenAI Codex / ChatGPT with code access \u2014 config and notes" } }, "workflows": { @@ -170,7 +209,9 @@ "documents": { "description": "Project specs, architecture docs, and written context for AI agents", "files": { - "README.md": "Index and intended contents for documents" + "README.md": "Index and intended contents for documents", + "onboarding.md": "Start-here checklist for new agents \u2014 network, git, AWS, k8s, red lines", + "machines.md": "Full machine inventory \u2014 Tabitha, Orson, Ozymandias, Hunter, GoatLord" } }, "analytics": { @@ -183,16 +224,16 @@ "description": "Per-client context for AI agents working on client engagements", "files": { "README.md": "Index of client files", - "aarete.md": "Aarete Group — DocyAI project context, repos, CI notes" + "aarete.md": "Aarete Group \u2014 DocyAI project context, repos, CI notes" } }, "projects": { "description": "Internal and personal project context", "files": { "README.md": "Index of project files", - "silma-ai.md": "Silma AI — platform overview, infrastructure, repos", - "banner-and-pyre.md": "MP Banner and Pyre — repo suite, Amplify deploy" + "silma-ai.md": "Silma AI \u2014 platform overview, infrastructure, repos", + "banner-and-pyre.md": "MP Banner and Pyre \u2014 repo suite, Amplify deploy" } } } -} +} \ No newline at end of file diff --git a/tools/k8s.llm.md b/tools/k8s.llm.md new file mode 100644 index 0000000..1890a2a --- /dev/null +++ b/tools/k8s.llm.md @@ -0,0 +1,144 @@ +# Kubernetes (k8s) Guide + +A local Kubernetes cluster runs on Tabitha under the `silma-ai` namespace. This is Silma's local data and infrastructure plane — databases, vector stores, message queues, secrets, observability, and workflow orchestration. + +--- + +## Cluster + +| Field | Value | +|-------|-------| +| **Context** | `docker-desktop` | +| **Namespace** | `silma-ai` | +| **Manifests** | `/Users/Tabitha/.openclaw/k8s/silma-ai/` | + +--- + +## Starting the Stack + +```bash +# Apply all manifests (idempotent) +bash /Users/Tabitha/.openclaw/k8s/silma-ai/scripts/apply.sh + +# Or via npm from the OCPlatform root +cd /Users/Tabitha/.openclaw && npm run k8s:silma-ai:ensure + +# Port-forward all services to localhost (run in a separate terminal, stays in foreground) +bash /Users/Tabitha/.openclaw/k8s/silma-ai/scripts/port-forward.sh +``` + +--- + +## Service Map + +All services below are accessible at `localhost:` **only when the port-forward script is running.** + +| Service | Port(s) | Auth | Notes | +|---------|---------|------|-------| +| **PostgreSQL + pgvector** | `5432` | secret: `postgres-credentials` | DB: `silma` — primary relational + vector store | +| **Redis** | `6379` | none | In-memory cache, pub/sub | +| **Elasticsearch** | `9200` | none | Full-text search | +| **Kafka** | `9092` | none | Event streaming (Zookeeper internal on 2181) | +| **Qdrant** | `6333` (HTTP), `6334` (gRPC) | none | Vector DB for Silma's semantic memory | +| **MinIO** | `9000` (API), `9001` (console) | secret: `minio-credentials` | S3-compatible object storage | +| **Vault** | `18200` | token: `devroot` | Secrets management — see `tools/vault.llm.md` | +| **Prometheus** | `9090` | none | Metrics scraper | +| **Grafana** | `3000` | secret: `grafana-admin` | Dashboards and observability UI | +| **Temporal** | `7233` (gRPC) | none | Workflow orchestration engine | +| **Temporal UI** | `8233` | none | Web UI for Temporal workflows | + +--- + +## LLM Inference (Host — NOT in k8s) + +LLM inference runs natively on Tabitha's host (not in Docker) to get Metal/GPU acceleration: + +```bash +cd /Users/Tabitha/.openclaw && npm run api:llm + +# Endpoints (OpenAI-compatible): +# Gemma-4-E4B: http://localhost:8080 +# Gemma-4-26B: http://localhost:8081 +``` + +--- + +## Common kubectl Commands + +```bash +# Check all pods +kubectl get pods -n silma-ai + +# Check a specific pod's logs +kubectl logs -n silma-ai --tail=50 +kubectl logs -n silma-ai -f # follow + +# Describe a pod (for debugging CrashLoopBackOff etc.) +kubectl describe pod -n silma-ai + +# Get secrets (base64-encoded) +kubectl get secret -n silma-ai postgres-credentials -o jsonpath='{.data.password}' | base64 -d + +# Restart a deployment +kubectl rollout restart deployment -n silma-ai + +# Get all resources in namespace +kubectl get all -n silma-ai + +# Check PVCs (persistent storage) +kubectl get pvc -n silma-ai +``` + +--- + +## Connecting to Services + +### PostgreSQL +```bash +# After port-forward is active: +psql -h localhost -p 5432 -U silma -d silma +# Password: from kubectl get secret postgres-credentials +``` + +### Qdrant (Silma's vector memory) +```python +from qdrant_client import QdrantClient +client = QdrantClient(host="localhost", port=6333) +client.get_collections() +``` + +### MinIO +```python +import boto3 +s3 = boto3.client('s3', + endpoint_url='http://localhost:9000', + aws_access_key_id='minioadmin', + aws_secret_access_key='minioadmin') +s3.list_buckets() +``` + +### Redis +```bash +redis-cli -h localhost -p 6379 ping +``` + +--- + +## Storage + +PVC data is persisted on Hagia (`/Volumes/Hagia/k8s/volumes/`). If Hagia is not mounted, PVCs will be unavailable and pods will fail to start. + +```bash +# Verify Hagia is mounted before starting k8s services +ls /Volumes/Hagia/k8s/volumes/ +``` + +--- + +## Notes for AI Agents + +- **Always run the port-forward script first** before trying to connect to any k8s service +- Tabitha must have Docker Desktop running with the `docker-desktop` context active +- If pods are in `CrashLoopBackOff`, check if Hagia is mounted — most PVCs depend on it +- Vault (`localhost:18200`) requires the port-forward — see `tools/vault.llm.md` for secret access patterns +- LLM inference is on the host, not in k8s — don't look for it with `kubectl` diff --git a/tools/tailscale.llm.md b/tools/tailscale.llm.md new file mode 100644 index 0000000..7b774a4 --- /dev/null +++ b/tools/tailscale.llm.md @@ -0,0 +1,101 @@ +# Tailscale Network Guide + +All machines in Jacob Mathison's environment are connected via Tailscale. This is the backbone of cross-machine access — SSH, kittens WebSocket bridges, Gitea, and local services all route over it. + +--- + +## Tailscale Account + +- **Account:** `silmaai2000@` (silmaai Tailscale account) +- **Network name:** silmaai2000's tailnet + +--- + +## Machine Inventory + +| Hostname | Tailscale IP | OS | Role | Status | +|----------|-------------|-----|------|--------| +| `macbook-pro-3` (Tabitha) | `100.76.192.116` | macOS arm64 | Silma AI primary — OCPlatform, k8s | ✅ Online | +| `orson` | `100.79.253.19` | macOS arm64 | Gitea host, CI runner (act_runner), Hagia attached | ✅ Online | +| `orson-macbook-pro` | `100.108.57.113` | macOS arm64 | Orson second interface | ✅ Online | +| `tabitha-macbook-pro` | `100.120.22.37` | macOS arm64 | Tabitha second interface | — | +| `ozymandiass-macbook-pro` (Ozymandias) | `100.115.222.5` | macOS x86_64 | Travel laptop / coding box | — Offline | +| `hunter-wsl2` | `100.118.15.20` | Linux (WSL2) | Hunter Albert's dev machine | — Offline | +| `joseph-bro-windows` | `100.123.22.58` | Windows | Aaron Pressey's machine (GoatLord) | — Offline | +| `mimir-mme3l` (Mimir) | `100.100.117.5` | Linux | Mimir server (Hunter's AI bridge box) | — Offline | + +--- + +## Verify Connectivity + +```bash +# Check your own Tailscale IP and status +tailscale ip +tailscale status + +# Ping a machine +ping 100.79.253.19 # Orson/Hagia/Gitea host +ping 100.76.192.116 # Tabitha (Silma primary) +``` + +--- + +## Connecting to Machines + +### Via kittens WebSocket bridge (preferred for remote exec) + +All machines run `silma-kittens` — a WebSocket server that allows remote command execution without needing SSH keys. + +```python +import asyncio, json, websockets + +async def remote(ip, cmd, token='silma-kittens-2026', timeout=20): + url = f'ws://{ip}:8765/?token={token}' + async with websockets.connect(url, open_timeout=5) as ws: + await ws.recv() + await ws.send(json.dumps({'type': 'exec', 'id': '1', 'cmd': cmd})) + r = json.loads(await asyncio.wait_for(ws.recv(), timeout=timeout)) + return r.get('stdout', ''), r.get('stderr', '') + +# Orson +out, err = asyncio.run(remote('192.168.12.138', 'hostname')) + +# Or via Tailscale IP +out, err = asyncio.run(remote('100.79.253.19', 'whoami')) +``` + +**Kittens token:** `silma-kittens-2026` (same on all machines) +**Port:** `8765` + +### Creon (Hunter's static ngrok tunnel) +Hunter's machine uses a permanent ngrok domain: +- **URL:** `wss://creon.ngrok.app/?token=3ClCIkJOCu1Gd5RO2PA4JHRD1ji_soHXcU4c3vMCbvEBFsKi` +- Requires `ngrok-skip-browser-warning: true` header + +--- + +## Key Service Endpoints (via Tailscale) + +| Service | Address | Notes | +|---------|---------|-------| +| Gitea | `http://100.79.253.19:3000` | Self-hosted git on Orson/Hagia | +| Tabitha k8s services | `localhost:*` when port-forwarded | See `tools/k8s.llm.md` | + +--- + +## /etc/hosts Entries (Tabitha) + +``` +100.79.253.19 Theodora Orson Hagia +``` + +These aliases are set on Tabitha — `Orson`, `Hagia`, `Theodora` all resolve to `100.79.253.19`. + +--- + +## Notes for AI Agents + +- If Tailscale is not connected, cross-machine operations will fail silently — verify with `tailscale status` first +- Gitea and kittens are both reachable via LAN IP (`192.168.12.x`) or Tailscale IP (`100.x.x.x`) when on the same network +- Offline machines have kittens installed but the tunnel won't be up — check `tailscale status` before trying +- GoatLord (`joseph-bro-windows`) also has a static ngrok URL: `exsufflicate-ineradicable-cortez.ngrok-free.app` (port 8765) diff --git a/tools/vault.llm.md b/tools/vault.llm.md new file mode 100644 index 0000000..69a7299 --- /dev/null +++ b/tools/vault.llm.md @@ -0,0 +1,107 @@ +# Vault Secrets Guide + +HashiCorp Vault runs in the `silma-ai` k8s namespace on Tabitha. It is the authoritative store for all credentials and API keys in this environment. + +--- + +## Access + +| Field | Value | +|-------|-------| +| **Host port** | `18200` (port-forwarded from k8s cluster port 8200) | +| **URL** | `http://localhost:18200` | +| **Root token** | `devroot` | +| **KV engine** | `silma/` (KV v2) | +| **UI** | `http://localhost:18200/ui` | + +⚠️ **Requires k8s port-forward to be active.** Run first: +```bash +bash /Users/Tabitha/.openclaw/k8s/silma-ai/scripts/port-forward.sh +``` + +--- + +## Quick Access via Helper Script + +```bash +cd /Users/Tabitha/.openclaw/workspace +bash scripts/vault.sh read +``` + +--- + +## Available Secrets + +| Path | Contents | +|------|---------| +| `discord` | `bot_token`, `client_id` | +| `telegram` | `bot_token` | +| `github/silma` | `username`, `pat`, `password` | +| `github/hunter` | `pat` | +| `twitter/silma` | `password` | +| `twitter/blb` | `email`, `password` | +| `buffer` | `email`, `password` | +| `spotify` | `username`, `password`, `client_id`, `client_secret`, `redirect_uri` | +| `google` | `password` | +| `gmail` | `imap_app_password` | +| `zoho` | `mail_password` | +| `aws` | `account_id`, `iam_username`, `iam_password`, `signin_url` | +| `reddit/silma-paws` | `username`, `email`, `password` | +| `reddit/silma-claws` | `username`, `email`, `password` | +| `hackerone` | `email`, `password` | +| `openclaw` | `gateway_token` | +| `patreon/blb` | `email`, `password` | +| `hunter/ngrok` | `creon_secret` | +| `api-keys/gemini` | `api_key` | +| `api-keys/nvidia` | `api_key`, `base_url` | +| `api-keys/runware` | `api_key` | +| `api-keys/eia` | `api_key` | +| `api-keys/airnow` | `api_key` | +| `api-keys/census` | `api_key` | +| `api-keys/noaa` | `token` | +| `api-keys/ticketmaster` | `api_key`, `secret` | +| `api-keys/banner-pyre` | `gemini_api_key`, `gcp_project` | + +--- + +## Reading Secrets (curl) + +```bash +VAULT_TOKEN=devroot +VAULT_ADDR=http://localhost:18200 + +# Read a secret +curl -s -H "X-Vault-Token: $VAULT_TOKEN" \ + "$VAULT_ADDR/v1/silma/data/discord" | python3 -m json.tool + +# Extract a specific field +curl -s -H "X-Vault-Token: $VAULT_TOKEN" \ + "$VAULT_ADDR/v1/silma/data/discord" \ + | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['data']['data']['bot_token'])" + +# List all secret paths +curl -s -H "X-Vault-Token: $VAULT_TOKEN" \ + -X LIST "$VAULT_ADDR/v1/silma/metadata/" \ + | python3 -c "import sys,json; d=json.load(sys.stdin); [print(k) for k in d['data']['keys']]" +``` + +--- + +## Writing Secrets + +```bash +# Write / update a secret +curl -s -H "X-Vault-Token: $VAULT_TOKEN" \ + -X POST "$VAULT_ADDR/v1/silma/data/my-secret" \ + -H "Content-Type: application/json" \ + -d '{"data": {"key": "value"}}' +``` + +--- + +## Notes for AI Agents + +- Vault is **only reachable on Tabitha** after the k8s port-forward is active +- The root token `devroot` is intentional for this local dev instance — do not rotate it without updating all scripts +- Prefer Vault over `credentials/secrets.env` for any new secrets — `secrets.env` is a fallback for when Vault isn't running +- Do not print or log full secret values — extract only the field you need