Glassdocs is a documentation-first stance for software transparency. Whoever wrote the code - a teammate, an inherited service, an AI agent - the docs live in your repo as HTML. Your team reads, curates, approves. Future work must stay aligned with what was accepted.
AI accelerated this, but the underlying problem is older: a codebase is only as transparent as its documentation, and documentation is the first thing teams cut. The result is a system your team owns on paper but can't fully see.
An inherited service. A junior's first PR. A 3 AM hotfix from six months ago. AI-authored work, today. Different sources, same outcome - you ship code your team can't fully explain.
Markdown exists to make typing prose ergonomic. When you do not type prose anymore - or when an agent emits HTML directly - keeping markdown in the pipeline is legacy infrastructure.
Whether the next contributor is a teammate or an AI prompt, they rediscover your codebase. No record of what was decided, no record of what was already accepted. Each change reinvents context.
A list of files changed and lines added does not tell you what your team chose, what it assumed, or what corners of the system the change quietly touched.
Three roles, three verbs. The loop runs the same whether the writer is a teammate, a contractor, or an AI agent. The docs are the contract for what is in your codebase.
Every change lands with documentation - written alongside the code, into docs/, as HTML.
One commit carries both the work and the human-readable explanation of what happened.
The docs are the diff you actually review. Visual, navigable, render in any browser without builds. Edit what is wrong, approve what is right. The accepted version becomes the record of truth.
The next contributor - human or agent - reads the approved docs before touching code. Work that contradicts them is flagged. The docs become the contract: enforced, not aspirational.
One command scaffolds a docs/ folder, the navigation shell, and the agent instructions that tell every contributor (human or AI) how to write into it.
Whatever lands - a feature, a refactor, a migration - lands with an HTML doc page explaining what, why, and where. No separate documentation task. No drift.
The docs ARE the diff your team reads. Visual, structured, navigable. Approve or edit the docs - and the code lands with them.
The Glassdocs extension feeds approved docs back into the next contributor's session - whether that is a teammate or an AI prompt. The contract follows the code.
<!-- Written 2026-04-23. Approved by @sergey. --> <article class="doc"> <h1>Session flow</h1> <p>Sessions are issued as signed cookies. Rotation happens on every privileged action.</p> <h2>Invariants</h2> <ul> <li>No token in localStorage.</li> <li>Cookie is httpOnly and SameSite=Lax.</li> </ul> </article>
AI accelerates the opacity crisis. You prompt, code appears, nobody fully read what shipped. Glassdocs applies the same loop to AI work as to human work - the agent documents what it built, your team reviews and accepts, the next prompt must respect what you accepted.
Whatever your AI builds comes with an HTML doc page in the same commit. No separate "now write the docs" step. Documentation is part of finishing the work.
Reviewing AI-written code line by line is impractical at the volume agents ship. Reviewing the doc that explains the change is faster and surfaces what actually matters.
The next agent task starts with the approved docs as context. Work that contradicts them is flagged before it lands - turning the docs into an enforcement surface, not just a reference.
The result is a codebase your team actually owns - readable by humans, respected by future agent work, audit-friendly by default. The blackbox becomes a glassbox.
Install the extension, point it at your repo, and the next change your team ships will come with a doc. Open source. MIT licensed. Free forever.