Problem: These two documents cover related but distinct agent design topics:

Agents — Formal definitions: Agent Specification, Instance, Session, Completion, Trigger.

Agents 2 — Brainstorming: Local Agent UI, Multiplayer Agents, Firecracker VM, Sub-Agents, Templates, Budgeting.

Neither document links to the other. A reader discovering one has no path to find the other.

Recommendation: Add a bidirectional cross-reference. At minimum, Agents 2 should link to Agents as the canonical definitions document. Agents should link to Agents 2 as the brainstorming/ideas extension.

Problem: Customizations with Code has a title that doesn't convey what the document is about. The content is specifically about how Exe.dev's Shelley agent modifies its own source code via Git clone → edit → rebuild → atomic replace.

Recommendation: Consider a more descriptive title such as:

"How Exe.dev Shelley Customizes Its Own Code"

"Shelley's Self-Modification via Git Rebase Pattern"

"Agent Self-Customization: The Exe.dev Approach"

Problem: Two new documents under /design/stories/settings/ have excessively long titles:

"⚠️As an admin, I want to publish my website with a free Hypermedia URL" (free-domain, 73 chars)

"⚠️As an admin, I want to publish my website with my own domain" (own-domain, 62 chars)

While the ⚠️ prefix is an established convention for "work in progress", these titles are unwieldy in navigation contexts. The user-story format belongs in the document body, not the title.

Recommendation: Shorten titles to:

"⚠️ Publish with a free Hypermedia URL"

"⚠️ Publish with my own domain"

The full user story can remain as the opening heading in each document.

Problem: This document went through 5+ versions on 2026-07-22, with significant restructuring between edits. The document interleaves a workflow pipeline (Setup → Ingestion → Processing → Retrieval → Eval) with domain-specific capacity questions about robotics, control systems, SLAM, and multi-agent research.

Recommendation: Consider splitting into two documents:

A concept page about the Capacity Questions methodology/workflow

A separate page with the example capacity questions for the specific domain

This would make each document more focused and linkable independently.

Problem: own-domain and free-domain are primarily video embeds and screenshots with minimal written content. Compared to admin-settings which has detailed acceptance criteria, edge cases, and flow descriptions, these are early-stage stubs.

Recommendation: As these mature, add acceptance criteria, edge cases, and basic flows following the pattern established by admin-settings. No action needed now — these are clearly in early shaping.

Problem: ⚠️ Edit URL path recently changed from "Edit path" to "⚠️ Edit URL path". A more discoverable title could be "Edit Document URL Path" to clarify this is about document URLs, not navigation paths.

Recommendation: Consider "⚠️ Edit Document URL Path" for clarity.