diff --git a/README.md b/README.md new file mode 100644 index 0000000..43fda58 --- /dev/null +++ b/README.md @@ -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/.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 with " +git push +``` + +--- + +*Maintained by [Jacob Mathison](mailto:jacob@mathisonprojects.com) · [Mathison Projects Inc](https://www.mathisonprojectsinc.com)* diff --git a/aws-cli.llm.md b/aws-cli.llm.md new file mode 100644 index 0000000..0da8bc6 --- /dev/null +++ b/aws-cli.llm.md @@ -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 --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---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 --payload '{}' output.json + +# Update function code (from zip) +aws lambda update-function-code --function-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 + +# Get current Amplify deployments +aws amplify list-apps --output table + +# Check a specific Amplify build +aws amplify list-jobs --app-id --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.