[DEV-6506] Reshape Lazurio documentation for technical readers

ARCHITECTURE.md

@@ -2,9 +2,10 @@
 
 ## Goal
 
-Provide one public, reviewable explanation of Lazurio for people and agents.
-The first consumer is an IT administrator who needs to understand the system,
-its trust boundaries and the operational decision before approving it.
+Provide one public, reviewable technical explanation of Lazurio for people and
+Task Agents. The first consumers are builders and technical evaluators who need
+to understand the system, create an Organization and connect their AI app.
+IT approval and operational controls remain a dedicated downstream path.
 
 ## Invariants
 
@@ -16,6 +17,8 @@ its trust boundaries and the operational decision before approving it.
    repository.
 6. A future MCP server may read the content index but cannot become a writer or
    a second content store.
+7. Product claims about host AI apps distinguish a verified in-app browser,
+   a side-by-side browser workflow and an unavailable native integration.
 
 ## Shape
 
@@ -45,8 +48,9 @@ portable deployment output. This repository intentionally excludes analytics,
 an editor, a private content import, migration history and unrelated assets.
 
 A standalone documentation repository is preferable to embedding the docs in
-a marketing site: documentation needs its own information architecture,
-evidence lifecycle, machine discovery contract and independent rollback.
+a marketing site: the website explains the product, while documentation owns
+technical procedures, examples, evidence lifecycle, machine discovery and
+independent rollback.
 
 ## Content identity
 

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## Unreleased
 
+- Reframe the English entry path for technical readers with a source-backed
+  quickstart, canonical glossary, Example Organization, component inventory,
+  real synthetic Launchpad screenshot and current AI app support matrix.
 - Establish the public Lazurio Documentation repository and Cloudflare Pages
   site.
 - Add the English IT trust briefing, system guide and Microsoft Copilot

README.md

@@ -1,13 +1,15 @@
 # Lazurio documentation
 
-Public, evidence-backed documentation for Lazurio. It is written first for
-people evaluating or operating Lazurio and structured so agents can discover
-the same canonical material without a second content store.
+Public, evidence-backed technical documentation for Lazurio. It is written
+first for builders, technical evaluators and operators, and structured so Task
+Agents can discover the same canonical material without a second content store.
 
-The first release is English-first. It starts with a ten-minute briefing for IT
-administrators and a sourced decision guide comparing Lazurio with Microsoft
-Copilot in the Microsoft 365 context. Czech follows after English content
-acceptance; it will be curated, not machine-published.
+The first release is English-first. It starts with the technical product model,
+current quickstart, a public-safe Example Organization, component/source map
+and truthful workflows for Codex, Claude, Cursor and Antigravity. IT controls
+and the sourced Microsoft Copilot comparison remain an operational and
+evaluation layer. Czech follows as a curated localization after English
+content acceptance.
 
 ## Application and deployment
 
@@ -54,8 +56,10 @@ owner and review window used by public claims.
 ## Current release boundary
 
 This repository does not implement an MCP server, chatbot, write API, analytics
-pipeline or private knowledge import. It does not claim certifications, legal
-compliance, a universal deployment model or a service-level agreement.
+pipeline or private knowledge import. It does not claim native integration
+where an AI app only supports a side-by-side browser workflow, nor
+certifications, legal compliance, a universal deployment model or a
+service-level agreement.
 
 ## License
 

app/v2/astro.config.mjs

@@ -19,6 +19,26 @@ function accessibleTables() {
   }
 }
 
+function accessibleCodeBlocks() {
+  return {
+    name: 'Accessible code blocks',
+    hooks: {
+      postprocessRenderedBlock({ renderData }) {
+        const visit = (node) => {
+          if (node.type === 'element' && node.tagName === 'pre') {
+            node.properties ??= {}
+            node.properties.tabIndex = 0
+            node.properties.ariaLabel = 'Scrollable code example'
+          }
+          if (Array.isArray(node.children)) node.children.forEach(visit)
+        }
+
+        visit(renderData.blockAst)
+      },
+    },
+  }
+}
+
 export default defineConfig({
   site: 'https://documentation.lazurio.ai',
   // Keep the locale prefix explicit so future curated locales can share root selection.
@@ -54,6 +74,9 @@ export default defineConfig({
       ],
       sidebar,
       customCss: ['./src/styles/docs.css'],
+      expressiveCode: {
+        plugins: [accessibleCodeBlocks()],
+      },
     }),
   ],
   adapter: cloudflare({

app/v2/scripts/query-content-index.test.mjs

@@ -16,6 +16,20 @@ test('agent index returns the comparison for a Copilot query', async () => {
   assert.ok(results.some((document) => document.stableId === 'lazurio-doc-copilot-comparison'))
 })
 
+test('agent index exposes the technical Organization and AI app guides', async () => {
+  const organizationResults = await queryContentIndex('Example Organization Launchpad file structure')
+  const appResults = await queryContentIndex('Codex Claude Cursor Antigravity support')
+
+  assert.ok(
+    organizationResults.some(
+      (document) => document.stableId === 'lazurio-doc-example-organization',
+    ),
+  )
+  assert.ok(
+    appResults.some((document) => document.stableId === 'lazurio-doc-use-with-ai-apps'),
+  )
+})
+
 test('agent retrieval resolves stable IDs and canonical routes', async () => {
   const byId = await getContentDocument('lazurio-doc-it-administrators')
   const byRoute = await getContentDocument('/en/it-administrators/')

app/v2/tests/documentation.spec.ts

@@ -5,26 +5,47 @@ test('the site root selects the accepted English locale', async ({ page }) => {
   await page.goto('/')
   await expect(page).toHaveURL(/\/en\/$/)
   await expect(
-    page.getByRole('heading', { level: 1, name: 'Lazurio: product, architecture and controls' }),
+    page.getByRole('heading', { level: 1, name: 'Lazurio technical documentation' }),
   ).toBeVisible()
 })
 
-test('the IT decision path is readable and navigable', async ({ page }) => {
+test('the technical start path reaches the quickstart and example Organization', async ({ page }) => {
   await page.goto('/en/')
   await expect(
-    page.getByRole('heading', { level: 1, name: 'Lazurio: product, architecture and controls' }),
+    page.getByRole('heading', { level: 1, name: 'Lazurio technical documentation' }),
   ).toBeVisible()
 
-  await page.getByRole('link', { name: 'For IT administrators' }).first().click()
-  await expect(page).toHaveURL(/\/en\/it-administrators\/$/)
-  await expect(page.getByRole('heading', { level: 1, name: 'Approval briefing for IT administrators' })).toBeVisible()
+  await page.getByRole('link', { name: 'Run the quickstart' }).first().click()
+  await expect(page).toHaveURL(/\/en\/quickstart\/$/)
+  await expect(page.getByRole('heading', { level: 1, name: 'Quickstart' })).toBeVisible()
+  await expect(page.getByText('bun run launchpad', { exact: true })).toBeVisible()
 
-  await page.getByRole('link', { name: 'Lazurio vs Microsoft Copilot' }).first().click()
-  await expect(page).toHaveURL(/\/en\/lazurio-vs-microsoft-copilot\/$/)
+  await page.getByRole('link', { name: 'Example Organization' }).first().click()
+  await expect(page).toHaveURL(/\/en\/example-organization\/$/)
+  await expect(page.getByRole('heading', { level: 1, name: 'Example Organization' })).toBeVisible()
+  await expect(
+    page.getByRole('img', { name: 'Launchpad showing the synthetic Lazurio Example Organization' }),
+  ).toBeVisible()
+})
+
+test('the AI app support matrix states the native integration limits', async ({ page }) => {
+  await page.goto('/en/use-with-ai-apps/')
+  await expect(page.getByRole('heading', { level: 1, name: 'Use Lazurio with AI apps' })).toBeVisible()
+  await expect(page.getByText(/Lazurio release does not publish a native Lazurio MCP server/)).toBeVisible()
+  await expect(page.getByRole('link', { name: 'Codex and ChatGPT Desktop' }).first()).toBeVisible()
+  await expect(page.getByRole('link', { name: 'Claude' }).first()).toBeVisible()
+  await expect(page.getByRole('link', { name: 'Cursor Glass' }).first()).toBeVisible()
+  await expect(page.getByRole('link', { name: 'Google Antigravity' }).first()).toBeVisible()
 })
 
 test('critical pages have no serious accessibility violations', async ({ page }) => {
-  for (const route of ['/en/', '/en/it-administrators/', '/en/lazurio-vs-microsoft-copilot/']) {
+  for (const route of [
+    '/en/',
+    '/en/quickstart/',
+    '/en/example-organization/',
+    '/en/use-with-ai-apps/',
+    '/en/it-administrators/',
+  ]) {
     await page.goto(route)
     const results = await new AxeBuilder({ page }).analyze()
     const serious = results.violations.filter((violation) =>
@@ -35,7 +56,7 @@ test('critical pages have no serious accessibility violations', async ({ page })
 })
 
 test('documentation tables keep readable cell spacing', async ({ page }) => {
-  await page.goto('/en/it-administrators/')
+  await page.goto('/en/use-with-ai-apps/')
   const table = page.locator('.sl-markdown-content table').first()
   const cells = table.locator('th, td')
 
@@ -71,6 +92,14 @@ test('documentation tables keep readable cell spacing', async ({ page }) => {
   expect(tableStyles.overflowX).toBe('auto')
 })
 
+test('scrollable code diagrams are keyboard focusable', async ({ page }) => {
+  await page.goto('/en/how-lazurio-works/')
+  const diagram = page.locator('.expressive-code pre').first()
+
+  await expect(diagram).toHaveAttribute('tabindex', '0')
+  await expect(diagram).toHaveAttribute('aria-label', 'Scrollable code example')
+})
+
 test('FAQ answers expand only after the reader opens them', async ({ page }) => {
   await page.goto('/en/faq/')
   const firstQuestion = page.locator('.sl-markdown-content details').first()

data/v2/docs/en/agents.md

@@ -3,8 +3,8 @@ title: Documentation for agents
 description: Stable discovery and retrieval surfaces for agents that need to understand Lazurio.
 stableId: lazurio-doc-agents
 summary: Use llms.txt and the content index to discover reviewed Lazurio pages, evidence links, audiences, review dates, and stable identities.
-updatedAt: "2026-08-26"
-reviewedAt: "2026-08-26"
+updatedAt: "2026-08-29"
+reviewedAt: "2026-08-29"
 reviewOwner: Matej Suchanek
 sourceRefs:
   - lazurio-readme
@@ -14,7 +14,7 @@ audience:
   - agent
 ---
 
-Agents should read the same reviewed source as people. This site does not keep
+Task Agents should read the same reviewed source as people. This site does not keep
 a hidden “AI version” of Lazurio documentation.
 
 ## Discovery surfaces
@@ -48,9 +48,10 @@ preview. Production deployment rejects a dirty or non-approved commit.
 6. If a statement is absent or deployment-specific, say so instead of filling
    the gap from inference.
 
-## Future MCP server
+## MCP compatibility seam
 
-A later read-only MCP server may expose discovery and retrieval over the same
-content index. It will not become a writer, private overlay or second content
-store. The current JSON contract is the compatibility seam for that work; the
-website does not depend on the future server.
+Lazurio does not currently ship a documentation MCP server. A read-only server
+can later expose discovery and retrieval over the same content index without
+becoming a writer, private overlay or second content store. The current JSON
+contract is the compatibility seam; today's website and agent retrieval do not
+depend on an MCP server.

data/v2/docs/en/antigravity.md

@@ -0,0 +1,61 @@
+---
+title: Google Antigravity
+description: Use a Google Antigravity Project and browser subagent with the exact Lazurio Launchpad URL.
+stableId: lazurio-doc-antigravity
+summary: Add a scoped Lazurio folder to an Antigravity Project, run Launchpad and open its local URL through the isolated browser subagent.
+updatedAt: "2026-08-29"
+reviewedAt: "2026-08-29"
+reviewOwner: Matej Suchanek
+sourceRefs:
+  - lazurio-readme
+  - lazurio-launchpad
+  - lazurio-collaboration-model
+  - antigravity-browser
+audience:
+  - builder
+  - agent
+---
+
+Google Antigravity Projects define which folders and repositories an Agent can
+access. Its browser subagent can open and operate local web apps, which makes
+it a practical current path to Launchpad.
+
+## Workflow
+
+1. Create an Antigravity Project.
+2. Add the Lazurio Root or one exact Organization or Module folder.
+3. Start an Agent session—the Task Agent in Lazurio terms—and ask it to read
+   the nearest `AGENTS.md`.
+4. Start Launchpad from the Lazurio Root:
+
+   ```sh
+   bun run launchpad
+   ```
+
+5. Copy the URL printed by the running instance.
+6. Invoke the browser workflow with the exact address:
+
+   ```text
+   /browser Open the Launchpad URL reported by the running Lazurio instance.
+   Verify the selected Organization and inspect Module status.
+   Do not open Personalspace or another Organization.
+   ```
+
+## Browser boundary
+
+Antigravity's browser runs in a separate Chrome profile. It does not
+automatically share cookies or active sessions from the person's normal
+browser. Its URL controls initialize with localhost allowed and can prompt for
+other domains.
+
+That isolation is a host-browser property. It does not create a second Lazurio
+IAM layer and does not grant access to repositories or hosted applications.
+
+## Project boundary
+
+Adding multiple folders gives the Agent cross-repository context. Use that
+capability only when the task genuinely spans those repositories. Never add a
+second Organization or a person's Personalspace to make discovery easier.
+
+Google's current browser behavior is documented in
+[Antigravity Browser](https://antigravity.google/docs/browser).

data/v2/docs/en/claude.md

@@ -0,0 +1,66 @@
+---
+title: Claude
+description: Use Claude Code as a Lazurio Task Agent and understand the current Claude Desktop boundary.
+stableId: lazurio-doc-claude
+summary: Start Claude Code from a scoped Lazurio checkout, keep Launchpad beside the session, and avoid claiming a Claude Desktop integration that Lazurio does not ship.
+updatedAt: "2026-08-29"
+reviewedAt: "2026-08-29"
+reviewOwner: Matej Suchanek
+sourceRefs:
+  - lazurio-readme
+  - lazurio-launchpad
+  - lazurio-external-apps
+  - anthropic-claude-code-cli
+  - model-context-protocol
+audience:
+  - builder
+  - agent
+---
+
+The current documented Claude workflow is **Claude Code working in a scoped
+Lazurio checkout**, with Launchpad open beside it in a browser.
+
+## Claude Code workflow
+
+1. Change into the exact Lazurio Root, Organization or Module:
+
+   ```sh
+   cd /path/to/Lazurio
+   claude
+   ```
+
+2. Ask Claude Code to read the nearest `AGENTS.md` before it makes changes.
+3. Start Launchpad from the Lazurio Root:
+
+   ```sh
+   bun run launchpad
+   ```
+
+4. Open the reported URL in a browser.
+5. Keep the Claude Code session and Launchpad on the same Machine and use the
+   exact Organization scope.
+
+Claude Code can add explicitly named working directories, but broader
+filesystem visibility is not a substitute for a well-scoped task. Do not add
+another Organization or Personalspace merely for convenience.
+
+## Claude Desktop status
+
+Claude Desktop supports MCP clients and local MCP-server configuration.
+However, the current Lazurio release does not ship a Lazurio MCP server,
+Claude Desktop extension or embedded Launchpad panel. Therefore there is no
+native Claude Desktop connection to configure in this release.
+
+Use Launchpad as a separate local application and Claude Code as the Task
+Agent. Do not install an unreviewed third-party bridge or paste Organization
+secrets into a generic connector to simulate native support.
+
+## External tools
+
+Lazurio's integration standard prefers an official local MCP server, then an
+official CLI, then a reviewed and pinned open-source server. Credentials remain
+per-Machine and revocable; the tracked repository contains only configuration
+shape and environment-variable names, never secret values.
+
+Anthropic's current CLI flags and `claude mcp` command are documented in the
+[Claude Code CLI reference](https://docs.anthropic.com/en/docs/claude-code/cli-usage).