llm-tools/README.md

# llm-tools

> **A phonebook for AI agents.** This repository exists so that Codex, Claude, Cursor, and any other LLM-based tool can orient themselves quickly in Jacob Mathison's development environment — without having to ask, guess, or explore blindly.

---

## What Is This?

When an AI agent starts working in this codebase, it often needs to answer basic questions:

- Where is the git server?
- What AWS account am I working in, and what's deployed?
- How do I authenticate?
- What other machines and services exist on the network?
- What projects are active?

This repo answers all of those questions. Think of it as a rolodex — structured reference docs, one per surface, that any LLM can read and immediately act on.

---

## Structure

```
llm-tools/
├── AGENTS.md           Instructions for AI agents working in this repo
├── README.md           This file
├── llm.txt             Plain-text overview for LLM agents
├── manifest.json       Machine-readable index of everything
│
├── 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
│   ├── tailscale.llm.md  Tailscale network — machines, IPs, kittens
│   ├── vault.llm.md      Vault secrets — paths, read patterns
│   ├── k8s.llm.md        k8s stack — services, ports, kubectl
│   ├── local-llm.llm.md  Local LLMs — Gemma-4-E4B (8080) + Gemma-4-26B (8081)
│   ├── claude-cli.md     Claude Code CLI reference
│   ├── codex-cli.md      OpenAI Codex CLI reference
│   ├── cursor-cli.md     Cursor IDE/CLI reference
│   └── discord.md        Discord bot — read/send channels, IDs, guild map
│
├── agents/             Per-agent configuration and notes
│   ├── README.md
│   ├── claude.md       ✅ filled
│   ├── cursor.md
│   └── codex.md
│
├── workflows/          Reusable workflows and automation
│   ├── README.md
│   └── job-search/
│       ├── linkedin.md
│       └── indeed.md
│
├── documents/          Project specs, architecture docs, written context
│   ├── 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
│
├── clients/            Per-client context and project notes
│   ├── README.md
│   └── aarete.md
│
└── projects/           Internal and personal project context
    ├── README.md
    ├── silma-ai.md
    └── banner-and-pyre.md
```

---

## Quick Start for an AI Agent

**1. Read `AGENTS.md`** — operational instructions and rules for working in this repo.

**2. Check your network access**
```bash
curl -s http://100.79.253.19:3000/api/v1/version   # Gitea — expect {"version":"1.26.2"}
aws sts get-caller-identity                         # AWS — expect account 567637986724
```

**3. Clone something**
```bash
# Any repo on the local Gitea (Tailscale required):
git clone http://100.79.253.19:3000/jacob-mathison/<repo>.git
```

**4. Read the guide for whatever surface you need**

| Need | Go to |
|------|-------|
| 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) |
| Local LLMs | [`tools/local-llm.llm.md`](./tools/local-llm.llm.md) |
| Claude Code CLI | [`tools/claude-cli.md`](./tools/claude-cli.md) |
| Codex CLI | [`tools/codex-cli.md`](./tools/codex-cli.md) |
| Cursor | [`tools/cursor-cli.md`](./tools/cursor-cli.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/) |

---

## Environment at a Glance

| Surface | Detail |
|---------|--------|
| **AWS Account** | `567637986724` — IAM user `jacob_mathison` (AdministratorAccess) |
| **AWS Default Region** | `us-east-1` |
| **AWS Profiles** | `default`, `mp-mac-tabitha` |
| **Gitea** | `http://100.79.253.19:3000` (Tailscale) |
| **GitHub (public work)** | https://github.com/MathisonProjects |
| **GitHub (Silma/AI)** | https://github.com/silmaai |
| **CI Runner** | `orson-runner` — act_runner v0.6.1, host mode, Node 24 on Orson |
| **Primary dev machine** | `Tabitha` (MacBook Pro arm64, `100.76.192.116`) |
| **Gitea host** | `Orson` / `Hagia` (`100.79.253.19`) |

---

## Conventions

- **Commits:** [Conventional Commits](https://www.conventionalcommits.org/) — `feat:`, `fix:`, `ci:`, `docs:`, `chore:`
- **Default branch:** `main`
- **Node (CI):** 20.x LTS
- **Package manager:** `npm`
- **IaC:** AWS Amplify Gen 2 for most frontend projects

---

## Keeping This Up to Date

When a new file, folder, service, or agent is added — update `manifest.json` and this `README.md`. See `AGENTS.md` for the full rules.

---

*Maintained by [Jacob Mathison](mailto:jacob@mathisonprojects.com) · [Mathison Projects Inc](https://www.mathisonprojectsinc.com)*