v1.15.0 ·
The link that spent three weeks as literal text
The website had one tutorial. getting-started was 64 lines: install, pick a template, run a session. It ended at the first instance and there was nothing after it.
Everything past that point lived in reference pages that answer questions you already know how to ask. A reader who had just finished their first session had no way to learn that cost tracking exists, that the knowledge graph stops the assistant re-reading the same code every session, that review gates are adversarial on purpose, or that two people can share a repo without colliding. Those are the reasons to adopt the framework, and they were invisible.
There was a quieter gap too. Nobody explained why the shape is the way it is: why an artifact is a file on disk and not chat history, why a roadmap item's status is its directory, why a claim exists at all. A reader who does not understand the shape fights it.
What shipped
A deep-dive series of eight chapters, at /tutorials/deep-dive/, with progress remembered in your own browser. The tutorials index now lists it as one entry, not nine flat pages. The chapters are markdown in the content package, and each can embed a small interactive piece through one new directive, {{widget:simulator/cost-attribution}}, which the site resolves against canned data. There are three kinds. A stepped recorded run shows a worked example. The same run with one command blanked asks you to supply it. A question about consequence hides its answer until you commit, then explains why the common wrong answer is tempting.
I rejected a plain long page, because the reader does nothing and quits. I rejected a fake terminal that accepts real commands, because it can only lie: it errors where the real CLI would succeed, or succeeds where it would fail. I also rejected a browser-saved mock project, because its state model would have to track the real one or teach something false. If readers finish the series and ask for more, that comes back as its own item.
One side effect I did not plan for. The {{ref:...}} directives in getting-started now render as links. That page had been showing readers the literal text {{ref:template/full-feature}} since it was written. It read correctly for the first time here.
Two fixes that rode along
Lead time on the release card read 0h for anything short. formatDuration in packages/website/src/components/blog/ReleaseCard.tsx now prints two units, always: hours and minutes under a day, days and hours at a day or more. It picks the branch from rounded minutes, so the 24-hour boundary belongs to exactly one form. The old day branch is byte for byte unchanged, checked over every value from 24 hours to 30 days. It had no tests, which is why 0h survived 27 posts. There are now 26, using the ten real wrong values as fixtures.
The CI actions moved to new majors: actions/checkout v4 to v7, actions/setup-node v4 to v7, and pnpm/action-setup v4 to v6, all on node24. ci/aidlc-gate.yml is not our CI. It is inlined into packages/content/tutorials/getting-started.md and shipped to users, so leaving it at v4 would have shipped the problem outward. I kept fetch-depth: 0 and an explicit cache: pnpm, each with its reason in the file, since both have burned this repo before. A new assertion in packages/website/src/test/ci-workflow.test.ts fails if the two workflows pin different versions of a shared action.
No CLI command, template or gate changed.