jacob-mathison/llm-tools
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add README and aws-cli.llm.md (phonebook for AI agents)

Browse Source
This commit is contained in:
Jacob Mathison
2026-05-30 23:29:53 -05:00
parent ddd32e2303
commit 30e1ecb827
2 changed files with 307 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+94
View File
@@ -0,0 +1,94 @@
# 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.
---
## Files
| File | What it covers |
|------|---------------|
| [`llm.txt`](./llm.txt) | Plain-text overview of this repo and the environment |
| [`manifest.json`](./manifest.json) | Machine-readable index: repos, CI, machines, conventions |
| [`gitea.llm.md`](./gitea.llm.md) | Local Gitea instance — clone URLs, PAT auth, API examples |
| [`aws-cli.llm.md`](./aws-cli.llm.md) | AWS account — profiles, S3, Amplify, CloudFront, Lambda |
---
## Quick Start for an AI Agent
**1. 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
```
**2. Clone something**
```bash
# Any repo on the local Gitea (Tailscale required):
git clone http://100.79.253.19:3000/jacob-mathison/<repo>.git
# This repo itself:
git clone http://100.79.253.19:3000/jacob-mathison/llm-tools.git
```
**3. Read the guide for whatever surface you need**
Working with source control → [`gitea.llm.md`](./gitea.llm.md)
Working with AWS → [`aws-cli.llm.md`](./aws-cli.llm.md)
---
## 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) |
| **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` (Mac mini, `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 you (a human or an AI agent) add a new service, machine, or repo, update the relevant file and push. The `manifest.json` especially should reflect the live state of the Gitea repo list.
```bash
cd /Volumes/Hagia/workspaces/workspace_Father/llm-tools
# edit the file(s)
git add .
git commit -m "docs: update <file> with <change>"
git push
```
---
*Maintained by [Jacob Mathison](mailto:jacob@mathisonprojects.com) · [Mathison Projects Inc](https://www.mathisonprojectsinc.com)*
aws-cli.llm.md
+213
View File
@@ -0,0 +1,213 @@
# AWS Access Guide
This document covers the AWS environment available to AI agents working in Jacob Mathison's stack.
---
## Account
| Field | Value |
|-------|-------|
| **Account ID** | `567637986724` |
| **IAM User** | `jacob_mathison` |
| **IAM Groups** | `Administrator-Access` (full access) |
| **Default Region** | `us-east-1` |
Verify identity:
```bash
aws sts get-caller-identity
```
---
## Profiles (`~/.aws/config`)
Two profiles are configured on local machines:
| Profile | Key ID | Notes |
|---------|--------|-------|
| `default` | `AKIAYIKO4JWSNZDZEMPK` | Primary — use for most operations |
| `mp-mac-tabitha` | `AKIAYIKO4JWSKH3W2JMY` | Tabitha machine-specific profile |
Using a named profile:
```bash
aws s3 ls --profile mp-mac-tabitha
```
---
## Active Amplify Apps
These are the live frontend deployments on AWS Amplify:
| App Name | App ID | Live URL |
|----------|--------|----------|
| `aarete-doczyai-app` | *(Gitea-hosted, not yet on Amplify)* | Local dev only |
| `mp-banner-and-pyre-web` | `d1k6pj7qv29ic0` | d1k6pj7qv29ic0.amplifyapp.com |
| `mp-midnights-eclipse` | `d166cwzk8nxlqn` | d166cwzk8nxlqn.amplifyapp.com |
| `mp-sora-compiler` | `dy0ryvla2yz9f` | dy0ryvla2yz9f.amplifyapp.com |
| `mp-silma-webapp` | `d390fbhya3a6oy` | d390fbhya3a6oy.amplifyapp.com |
| `ams-enterprises` | `d3grlr6dp3vfy4` | d3grlr6dp3vfy4.amplifyapp.com |
| `catholic-knights-hub` | `d2jhrecnjwpdbj` | d2jhrecnjwpdbj.amplifyapp.com |
| `insight-technologies-web-app` | `d3qk956gxa1uoo` | d3qk956gxa1uoo.amplifyapp.com |
| `silma-usdw` | `d1x1hodshtm3dr` | d1x1hodshtm3dr.amplifyapp.com |
| `Mathison Projects Inc` | `do1739t99tnux` | do1739t99tnux.amplifyapp.com |
| `hunter-website-frontend` | `d2b2fe8ej44qml` | d2b2fe8ej44qml.amplifyapp.com |
| `eloi-web-app` | `d1kgq6f5c0qics` / `d2rtpwrs0up8wz` | Two deployments |
| `db-death-to-you` | `d7gah601krim0` | d7gah601krim0.amplifyapp.com |
| `platamus-ai-web` | `d1kk3q6o3gwhmv` | d1kk3q6o3gwhmv.amplifyapp.com |
| `mp-true-auto-test` | `d3omnsbg4y5qym` | d3omnsbg4y5qym.amplifyapp.com |
```bash
# List all apps
aws amplify list-apps --query 'apps[].{name:name,appId:appId}' --output table
# Get branches for a specific app
aws amplify list-branches --app-id d1k6pj7qv29ic0
# Trigger a deployment
aws amplify start-job --app-id <appId> --branch-name main --job-type RELEASE
```
---
## S3 Buckets (Notable / Active)
There are 100+ buckets in this account. Here are the meaningful ones grouped by project:
### Mathison Projects / MPRNDC Platform
```
mathisonprojectsinc-media-storage General media storage
mathisonprojectsinc.com Website bucket
mpfilesrepositorybucket File repository
mp-codecommit-backup CodeCommit backups
```
### Amplify Deployment Buckets (auto-managed)
Pattern: `amplify-<appname>-<branch>-deployment`
These are managed by Amplify — do not modify directly.
### Active Project Buckets
```
mp-silma-webapp-storage-7eb39ce6163613-main Silma webapp storage
ams-enterprises-blog-media67aeb-main AMS Enterprises blog media
amplify-amsenterprises-main-67aeb-deployment AMS deployment bucket
catholicknightshubbcce21... Catholic Knights Hub
mpmidnightseclipse9c9853... Midnights Eclipse
budget-app-frontend-demo-* Budget app (demo iterations)
yield-curve-frontend-567637986724-us-east-1 Yield curve app
mp-star-wars-crawl-ttrpg-bucket Star Wars TTRPG crawl
channelwatcherstack-imagebucket* Channel watcher CDK stack
jobtrackerfrontendstack-sitebucket* Job tracker CDK stack
```
### Older / Archive
```
carbon-canyon Old project
carbon-canyon-images Old project assets
hunter-website-bucket Hunter's site (older)
```
```bash
# List all buckets
aws s3 ls
# List contents of a bucket
aws s3 ls s3://mp-silma-webapp-storage-7eb39ce6163613-main/
# Copy a file up
aws s3 cp ./file.txt s3://bucket-name/path/file.txt
# Sync a directory
aws s3 sync ./dist s3://bucket-name/ --delete
```
---
## CloudFront Distributions
| Domain | Distribution ID | Origin |
|--------|----------------|--------|
| `d7my3848sxi7h.cloudfront.net` | `E2LURYI96JEZUF` | nodoor S3 |
| `d3iqqrk40rv7wp.cloudfront.net` | `E1ZMK2VOWD8N7D` | thelatestbyte S3 |
| `d33k0vx8ugjsbl.cloudfront.net` | `E3FJ0C9KZ2P66V` | agodsfate (dev) S3 |
| `dmbj78hmp5pqz.cloudfront.net` | `E3PZUTQE470RWU` | agodsfate (cursedwish) S3 |
| `d7rq6agluf3t1.cloudfront.net` | `E19MH6OHBRAJMS` | budget app (demo) S3 |
| `dyg0pi8t1yiry.cloudfront.net` | `E168A4ZM76UTOD` | budget app (dev) S3 |
| `di0znvwek65ph.cloudfront.net` | `E2DJQ22UPEMH76` | yield curve S3 |
| `d2r090auwn8r8q.cloudfront.net` | `E2LQD2SHZJ9X12` | Midnights Eclipse S3 |
| `d39zkcuwj614ch.cloudfront.net` | `E3E7BJ3V0GRSPL` | Catholic Knights Hub S3 |
| `d3nyy5vutr3d2o.cloudfront.net` | `E16EKCKZGH1AWI` | Star Wars TTRPG S3 |
| `d1nbxkp08f37uh.cloudfront.net` | `E3TAZ95XVMILZN` | Lambda URL origin |
| `d3kkup0oojcdt1.cloudfront.net` | `E2UTIV86EU1KTG` | Hunter webdev apex redirect |
| `d20fik8n5hnz6v.cloudfront.net` | `EXXQI20BUIETJ` | EC2 origin |
```bash
# List distributions
aws cloudfront list-distributions --query 'DistributionList.Items[].{id:Id,domain:DomainName}' --output table
# Invalidate cache (force fresh deploy)
aws cloudfront create-invalidation --distribution-id E3FJ0C9KZ2P66V --paths "/*"
```
---
## Lambda Functions (us-east-1, selected)
| Function Name | Runtime | Notes |
|---------------|---------|-------|
| `CatholicKnightsHubTransactionLambda-main` | nodejs22.x | Catholic Knights Hub transactions |
| `NBS-Email-Lambda` | nodejs14.x | Email sending (old) |
| `Nodoor-RouterLambdaEntry-3GPR2Oa1SisY` | nodejs18.x | Nodoor routing |
| `amplify-login-*` | nodejs20.x | Amplify auth challenge handlers |
```bash
# List all Lambda functions
aws lambda list-functions --region us-east-1 --query 'Functions[].FunctionName' --output text
# Invoke a function
aws lambda invoke --function-name <name> --payload '{}' output.json
# Update function code (from zip)
aws lambda update-function-code --function-name <name> --zip-file fileb://function.zip
```
---
## Useful AWS CLI Patterns
```bash
# Check what you have access to
aws sts get-caller-identity
# Find a bucket by partial name
aws s3 ls | grep <keyword>
# Get current Amplify deployments
aws amplify list-apps --output table
# Check a specific Amplify build
aws amplify list-jobs --app-id <appId> --branch-name main --max-results 5
# List DynamoDB tables
aws dynamodb list-tables --region us-east-1
# List Cognito user pools
aws cognito-idp list-user-pools --max-results 20 --region us-east-1
# List API Gateways
aws apigateway get-rest-apis --region us-east-1
# Check CloudFormation stacks
aws cloudformation list-stacks --stack-status-filter CREATE_COMPLETE UPDATE_COMPLETE --query 'StackSummaries[].StackName' --output text
```
---
## Notes for AI Agents
- **AdministratorAccess** is in effect — you can do anything in this account. Be careful with destructive operations. Always prefer non-destructive reads first.
- **Prefer `--dry-run`** on EC2 operations and `--dryrun` on S3 sync when in doubt.
- **Amplify is the standard deploy path** for frontend projects — use `aws amplify start-job` rather than manually pushing to S3.
- **Don't delete S3 buckets** — they often back CloudFront distributions and Amplify deployments.
- **Region is `us-east-1`** unless otherwise specified. A few resources may exist in other regions.