Nice implementation — the URL fragment trick for privacy is clever.
Related pattern I've leaned into heavily: treating .md files as structured state the agent reads back, not just output. YAML frontmatter parsed as fields (status, dependencies, ids), prose only in the body. Turns them from "throwaway outputs" into state the filesystem enforces across sessions — a new session can't silently drift what was decided in the previous one.
Your styling-via-frontmatter is the same mechanism applied to presentation. Have you thought about a read mode that exposes the frontmatter as structured data, for agents that consume sdoc URLs downstream?
I think the next thing I want to do (but not sure how to implement yet) is to make it easy for your agent to go from SDocs url to content. I don't know if that's via curl or a `sdoc` command, or some other way... That could include the styling Front Matter / the agent could specify it.
At the moment the most efficient way to get sdocs content into an agent is to copy the actual content. But I think that's not too beautiful.
That direction makes a lot of sense. If sdoc could output raw content — or parsed frontmatter and body separately — to stdout, agents could consume it directly without a browser step. Something like sdoc get <url> --format json piped into whatever the agent needs next.
The frontmatter-as-structured-data angle is where it gets interesting: an agent reading frontmatter as JSON could use it for routing, status checks, dependency resolution — not just presentation. Basically turning a sdoc URL into a queryable state artifact, not just a readable document.
I've been switching between both depending on which one is having a good week — and that's the honest answer for most people right now.
But the real issue I ran into wasn't which model is better. It's that every time I switched, I lost weeks of accumulated context. The AI didn't know my project's conventions anymore, didn't remember the architecture decisions, didn't know what was tried and rejected.
What helped me was separating the project context from the tool. Keep the conventions, rules, and decisions in plain files in the repo. Both Claude Code and Codex can read them at session start. Then the question becomes "which model is sharper this week" instead of "can I afford to lose my context."
The answer to your question: it's mostly a wash on capability. The real cost of switching is the context you don't realize you're rebuilding.
Related pattern I've leaned into heavily: treating .md files as structured state the agent reads back, not just output. YAML frontmatter parsed as fields (status, dependencies, ids), prose only in the body. Turns them from "throwaway outputs" into state the filesystem enforces across sessions — a new session can't silently drift what was decided in the previous one.
Your styling-via-frontmatter is the same mechanism applied to presentation. Have you thought about a read mode that exposes the frontmatter as structured data, for agents that consume sdoc URLs downstream?
reply