<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/2.x/2026-02-23-3-versioned-1x-2x-docs-site-without-hosted-platform-scope/">
  <id>https://docs.spec-kitty.ai/adr/2.x/2026-02-23-3-versioned-1x-2x-docs-site-without-hosted-platform-scope/</id>
  <title>Versioned 1.x/2.x Documentation Site Without Hosted-Platform Scope</title>
  <updated>2026-02-23T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/2.x/2026-02-23-3-versioned-1x-2x-docs-site-without-hosted-platform-scope/"/>
  <summary>Splits the documentation site into explicit 1.x and 2.x tracks behind a versioned landing page, while deliberately holding hosted-platform guidance out of scope.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;The docs site historically served one blended track, making 1.x and 2.x behavior difficult to separate. Meanwhile, 2.x introduced doctrine/glossary architecture that lacked a clear documentation path.&lt;/p&gt;
&lt;p&gt;For this release, documentation scope must remain local-first and must not add hosted-platform guidance.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;Present 1.x and 2.x behavior as distinct, navigable tracks.&lt;/li&gt;
&lt;li&gt;Document 2.x doctrine/glossary architecture accurately.&lt;/li&gt;
&lt;li&gt;Prevent accidental reintroduction of out-of-scope hosted-platform docs.&lt;/li&gt;
&lt;li&gt;Keep docs deployment straightforward through existing GitHub Pages flow.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;Keep a single unversioned documentation track.&lt;/li&gt;
&lt;li&gt;Create explicit &lt;code dir=&quot;auto&quot;&gt;docs/1x/&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;docs/2x/&lt;/code&gt; tracks with a versioned landing page (chosen).&lt;/li&gt;
&lt;li&gt;Split docs into separate repositories.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen option:&lt;/strong&gt; Create explicit &lt;code dir=&quot;auto&quot;&gt;docs/1x/&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;docs/2x/&lt;/code&gt; tracks with a versioned landing page and docs guardrails.&lt;/p&gt;
&lt;h3 id=&quot;decision-details&quot;&gt;Decision Details&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;Documentation navigation is versioned at top level (&lt;code dir=&quot;auto&quot;&gt;1.x&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;2.x&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;2.x track documents doctrine architecture, charter workflow, glossary system, mission/runtime loop, and ADR coverage.&lt;/li&gt;
&lt;li&gt;1.x track remains local-first and excludes hosted-platform guidance in this docs path.&lt;/li&gt;
&lt;li&gt;Docs CI includes versioned-doc checks for link integrity and forbidden out-of-scope terms in versioned pages.&lt;/li&gt;
&lt;li&gt;GitHub Pages workflow deploys documentation updates from both &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;2.x&lt;/code&gt; branches.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;consequences&quot;&gt;Consequences&lt;/h3&gt;
&lt;h4 id=&quot;positive&quot;&gt;Positive&lt;/h4&gt;
&lt;ol&gt;
&lt;li&gt;Users can immediately choose the correct version track.&lt;/li&gt;
&lt;li&gt;2.x architecture changes are documented where users expect them.&lt;/li&gt;
&lt;li&gt;Docs quality gates detect broken links and scope drift early.&lt;/li&gt;
&lt;/ol&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ol&gt;
&lt;li&gt;Documentation maintenance now spans two version tracks.&lt;/li&gt;
&lt;li&gt;Some legacy unversioned docs may require gradual migration into versioned pages.&lt;/li&gt;
&lt;/ol&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ol&gt;
&lt;li&gt;Existing source docs can continue to exist while versioned tracks become canonical.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h2&gt;
&lt;p&gt;This decision is validated when:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Versioned docs build and link checks pass.&lt;/li&gt;
&lt;li&gt;1.x and 2.x top-level docs are both navigable in GitHub Pages.&lt;/li&gt;
&lt;li&gt;Doctrine/glossary 2.x architecture is documented and cross-referenced to ADRs/code.&lt;/li&gt;
&lt;li&gt;Versioned docs tests fail on banned out-of-scope hosted-platform terms.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;p&gt;Implementation references:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;docs/index.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;docs/toc.yml&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;docs/1x/*.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;docs/2x/*.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;docs/docfx.json&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;.github/workflows/docs-pages.yml&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/docs/test_versioned_docs_integrity.py&lt;/code&gt;&lt;/li&gt;
&lt;/ol&gt;</content>
</entry>
