From 0c07e90cb01e8306151c1c11a2df3adf57d686b3 Mon Sep 17 00:00:00 2001
From: Prad Nukala <prad@sonr.io>
Date: Thu, 25 Jun 2026 14:29:55 -0400
Subject: [PATCH] docs(agents): add documentation for agents directory and its
 contents

---
 docs/AGENTS.md           | 45 ++++++++++++++++++++++++++++++++++++++++
 docs/projects/floadt.yml | 14 +------------
 2 files changed, 46 insertions(+), 13 deletions(-)
 create mode 100644 docs/AGENTS.md

diff --git a/docs/AGENTS.md b/docs/AGENTS.md
new file mode 100644
index 0000000..1916496
--- /dev/null
+++ b/docs/AGENTS.md
@@ -0,0 +1,45 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-06-25 | Updated: 2026-06-25 -->
+
+# docs
+
+## Purpose
+Structured YAML source material for the résumés — the canonical, role-agnostic record of Prad's career. The `src/*.tex` variants are hand-curated *from* this data; nothing here is generated and nothing generates the `.tex`. Treat these files as the single source of truth: when a fact changes (a date, a metric, a new project), update it here first, then reflect it in the relevant templates.
+
+## Subdirectories
+Each subdirectory holds one flat collection of like-shaped YAML files (no nesting, no per-file AGENTS.md — they share a schema described below).
+
+| Directory | Purpose |
+|-----------|---------|
+| `experience/` | One file per employer (`sonr`, `leidos`, `britetwist`, `hobsons`, `unissant`). Fields: `title`, `company`, `start`/`end`, `location`, `description` (bullets), `skills`, `projects` (refs). |
+| `projects/` | One file per project (16). Fields: `title`, `start`/`end`, `project-url`, `associated-with`, `skills`, `description` (bullets). Sonr-era projects (appchain, beam-chat, cryptography-library, client-sdk, token-economics, decentralized-airdrop, ecosystem-devrel) carry the strongest material. |
+| `skills/` | `languages.yml` (expert/strong/familiar tiers), `frameworks.yml` (grouped flat list), `methodology.yml` (flat list). These feed the Skills column in the templates. |
+| `recognition/` | `honors.yml` (e.g. MIT Sloan guest lecture) and `organizations.yml` (W3C, DIF working groups). Feed the Honors/Organizations blocks. |
+| `information/` | `profile.yml` (name, contact, role summaries) and `education.yml` (VCU, Applied Math). |
+
+## For AI Agents
+
+### Working In This Directory
+- Cross-references use relative paths (e.g. `associated-with: ../experience/sonr.yml`). Keep them valid when renaming/moving files.
+- `description` blocks are YAML block scalars (`|`) of Markdown-style `- ` bullets. These bullets are the raw pool the templates draw from — condensed, not copied verbatim, to fit one page.
+- This is **data, not a build input.** Editing YAML does not change any PDF until a human/agent edits the corresponding `src/*.tex`.
+
+### Testing Requirements
+No build step. Validate that edited files still parse:
+```bash
+python3 -c "import yaml; yaml.safe_load(open('<file>.yml'))"
+```
+
+### Common Patterns
+- Skill names are kept consistent across files (e.g. "Decentralized Identifiers (DIDs)", "WebAssembly (WASM)") so they can be matched and deduplicated.
+- Dates are ISO `YYYY-MM-DD`; templates render them as year ranges.
+
+## Dependencies
+
+### Internal
+- Consumed by `../src/*.tex` (by hand) and indirectly by `../CLAUDE.md` guidance.
+
+### External
+- None — plain YAML, no schema/validation tooling configured.
+
+<!-- MANUAL: Any manually added notes below this line are preserved on regeneration -->
diff --git a/docs/projects/floadt.yml b/docs/projects/floadt.yml
index 33f9923..0dac432 100644
--- a/docs/projects/floadt.yml
+++ b/docs/projects/floadt.yml
@@ -1,16 +1,4 @@
 title: Floadt
 start: 2013-05-01
 end: 2015-10-01
-project-url:
-skills:
-  - Game Development
-  - Objective-C
-  - Cocos2d
-description: |
-  - Developed and launched a puzzle-based casual game for iOS using the Cocos2D framework and Objective-C at age 12.
-  - Navigated the constraints of early iOS development by successfully managing memory allocation manually, prior to the introduction of built-in automated memory management.
-  - Designed the complete game loop, mechanics, and user interface tailored specifically for the mobile casual gaming market.
-media:
-  - url: https://vimeo.com/172015296
-    caption: Superball Promo Video
-associated-with: ../experience/britetwist.yml
+project-url: https://github.com/prdlk/floadt