docs: per-folder navigation guides for resources/ and server/

[kriszyp]

Summary

Adds two new per-folder navigation docs and expands AGENTS.md so agents can find code without grepping blindly or reading 4744-line files top-to-bottom.

• resources/DESIGN.md — section index for Table.ts (grouped by responsibility: setup, authz, read path, write path, search, pub/sub, validation, stats, history) and a Resource.ts member table with line numbers. Includes a "Where is X" cheat sheet.
• server/DESIGN.md — clarifies that three HTTP stacks coexist (native http.ts, Operations API on Fastify in operationsServer.ts, legacy Custom Functions on Fastify in fastifyRoutes.ts). Adds an http.ts section index, file-by-file map of every server file, and notes on middleware ordering.
• AGENTS.md — adds a repository map for all 19 top-level folders, a "Detailed navigation" pointer table to the new docs, and updates the "two HTTP stacks" wording to three.

Goal

Reduce the overhead of starting a task in this repo. Pain points (raised by the user): agents spend time grepping the wrong folders and reading large files unnecessarily.

Where to put attention

• Three HTTP stacks claim — the existing AGENTS.md said two; I split out operationsServer.ts as a separate stack since it boots its own Fastify instance independently of fastifyRoutes.ts. If you'd prefer to keep these grouped as one "Fastify layer", let me know — it's a one-paragraph change.
• Line numbers in section indexes — every line number was spot-checked against the actual file (verified _writeUpdate at 1589, search() at 2022, subscribe() at 2640, getFromSource at 4062, etc.), but they will drift as Table.ts is edited. If we want these to stay accurate long-term we may want a CI check, or to switch from line numbers to anchor comments in the source. Open to suggestions.
• resources/analytics/ vs harper-pro/analytics/ — the docs call out that these are different (request telemetry vs CPU profiling). Worth confirming I have the boundary right.
• No new code, no test changes — this is documentation only. No build or test impact.

Test plan

• Verified all referenced files and line numbers exist (Resource.ts:41,461,475,688,735; Table.ts:1589,1942,2022,2640,4062,4607; http.ts:274,299,582,625,662,743)
• Verified folder contents claimed in the repository map
• Prettier-formatted
• Reviewer should sanity-check the three-stack framing in server/DESIGN.md

---

Generated by Claude Opus 4.7 (1M context) via the harper-engineering-guidelines skill.

[claude]

Reviewed; no blockers found.

[Ethan-Arrowood]

line-based guides like this creates a new maintenance burden. How do we ensure these will be updated when someone (or some agent) modifies source code?

Unless there is a process to ensure that these docs are always correct (as to not misguide future agents), I'd rather documents like this stop at the higher-level what stuff is in what files. Then it's the agent's responsibility to read the source when its making a contribution. But not necessarily read everything to figure out where.

[kriszyp]

line-based guides like this creates a new maintenance burden. How do we ensure these will be updated when someone (or some agent) modifies source code?

Unless there is a process to ensure that these docs are always correct (as to not misguide future agents), I'd rather documents like this stop at the higher-level what stuff is in what files. Then it's the agent's responsibility to read the source when its making a contribution. But not necessarily read everything to figure out where.

This is the intended procedure for how we ensure that it is maintained (that all Harper engineers should use for PRs):
https://github.com/HarperFast/skills-internal/blob/main/skills/harper-engineering-guidelines/SKILL.md?plain=1#L50-L52

Do you think that's sufficient?
From what I have observed, agents do tend to do a lot of grepping of large modules like Table.ts to avoid having to read it all (lots of tokens, and a fix may not necessarily go in that module), and this seems like it should get high level information in context faster and more efficiently. Claude did believe this would help future tasks. But this is hard to prove.