Ready For V1

.github/workflows/ci.yml

@@ -0,0 +1,72 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main, master]
+  # Link rot is time-based, not commit-based, so also run on a schedule.
+  schedule:
+    - cron: '0 6 * * 1'
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build and lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - run: npm ci
+
+      # Fails on any broken internal link (onBrokenLinks: 'throw').
+      - name: Build site
+        run: npm run build
+
+      - name: Typecheck
+        run: npm run typecheck
+
+      # Errors (missing title/description/keywords) fail; length warnings do not.
+      - name: Lint front matter
+        run: npm run lint:frontmatter
+
+  verify-api:
+    name: Verify docs against published packages
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      # Deliberately installs from PyPI rather than a sibling checkout: the docs
+      # must match the packages readers actually get.
+      - name: Install AgentFlow
+        run: pip install 10xscale-agentflow 10xscale-agentflow-cli
+
+      - name: Verify documented symbols, routes, and commands exist
+        run: npm run verify:api
+
+  links:
+    name: External links
+    runs-on: ubuntu-latest
+    # A third-party outage should surface as a warning, not a red PR.
+    continue-on-error: ${{ github.event_name == 'pull_request' }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Check external links
+        run: node scripts/check-external-links.mjs

docs/courses/COURSE_STYLE_GUIDE.md → COURSE_STYLE_GUIDE.md

@@ -1,18 +1,7 @@
----
-title: Course Style Guide — AgentFlow Python AI Agent Framework
-sidebar_label: Course Style Guide
-description: Standards and template for writing GenAI course lessons. Part of the AgentFlow genai course guide for production-ready Python AI agents.
-keywords:
-  - genai course
-  - ai agent course
-  - agent engineering course
-  - agentflow
-  - python ai agent framework
-  - course style guide
----
-
+# Course style guide
 
-# Course Style Guide
+Standards and template for writing GenAI course lessons under `docs/courses/`.
+This file lives outside `docs/` on purpose: it is an authoring reference, not a published page.
 
 This guide defines the standards for writing lessons in the GenAI Beginner and Advanced courses.
 

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 10xScale
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -50,14 +50,27 @@ Static output in `build/`.
 
 > **Windows + Git Bash note:** if `npm run build` mangles `BASE_URL=/` (you'll see broken links resolving to `C:/Program Files/Git/...`), run from PowerShell with `$env:MSYS_NO_PATHCONV='1'`.
 
-## SEO scripts
+## Checks
 
 ```bash
-npm run seo:audit       # lint per-page front matter (title, description, keywords)
-npm run seo:fix         # auto-fill missing/short SEO front matter (idempotent)
-npm run seo:og-image    # convert SVG social card to PNG (requires `sharp`)
+npm run build              # fails on any broken internal link
+npm run typecheck
+npm run lint:frontmatter   # every page needs title, description, keywords
+npm run lint:links         # every external URL must resolve
+npm run verify:api         # documented symbols, routes, and commands must exist
+npm run og-image           # regenerate the PNG social card from the SVG
 ```
 
+`verify:api` checks the docs against the packages published to PyPI, which is
+what readers actually install:
+
+```bash
+pip install 10xscale-agentflow 10xscale-agentflow-cli
+npm run verify:api
+```
+
+All of these run in CI (`.github/workflows/ci.yml`).
+
 ## Deploy
 
 `.github/workflows/deploy.yml` builds and deploys to GitHub Pages on push to `main`.
@@ -74,38 +87,54 @@ The site is configured for the custom domain **agentflow.10xscale.ai** (CNAME in
 ```text
 docs/
   get-started/         # golden path, beginner-friendly
-  concepts/            # mental models
-  beginner/            # tutorial path
+  beginner/            # guided tutorial path
+  concepts/            # mental models, with an "In depth" tier beneath
+  prebuild/            # prebuilt agents and tools
+  how-to/              # task-oriented guides (python, production, cli, client)
+  qa/                  # unit testing and evaluation
   tutorials/           # from-examples deep dives
-  how-to/              # task-oriented guides
-  reference/           # API reference (Python, REST, TS client)
-  compare/             # framework comparisons (LangGraph, CrewAI, AutoGen, etc.)
+  reference/           # API reference (Python, REST, CLI, TS client)
+  troubleshooting/
   use-cases/           # production reference architectures
   integrations/        # FastAPI / Next.js / Postgres
   providers/           # LLM provider configuration
-  troubleshooting/
+  glossary/            # definition pages
+  compare/             # framework comparisons (LangGraph, CrewAI, AutoGen, etc.)
   courses/             # GenAI beginner + advanced curriculum
+  project/             # changelog, upgrade guide, roadmap, security, support
 
-blog/                  # 10 cornerstone posts, RSS at /blog/rss.xml
+blog/                  # cornerstone posts, RSS at /blog/rss.xml
 src/
   components/          # CompareTable, FAQ, RelatedDocs, BlogStructuredData
   pages/               # Homepage
   theme/               # MDXComponents, Root swizzles
-static/                # CNAME, robots.txt, social card, favicon
-scripts/               # SEO automation (audit, fix, og-image)
-marketing/             # Launch kit (HN/Reddit/dev.to), measurement playbook
-SEO_PLAN.md            # Full SEO plan (Parts A–F)
+static/                # CNAME, robots.txt, llms.txt, social card, favicon
+scripts/               # front-matter, link, and API-drift checks
+COURSE_STYLE_GUIDE.md  # authoring rules for docs/courses (not published)
 ```
 
+Docs versions are cut only when a release line needs to stay available:
+
+```bash
+npm run docs:cut-version -- 1.0
+```
+
+That snapshots `docs/` into `versioned_docs/version-1.0`; the navbar version
+dropdown then appears automatically.
+
 ## Contributing
 
-PRs welcome. Before opening:
+PRs welcome. Before opening one, run the checks above.
+
+Writing conventions, where a page belongs, and the release process are
+documented on the site: [Contributing](https://agentflow.10xscale.ai/docs/project/contributing).
 
-1. `npm run typecheck`
-2. `npm run build` (verify no broken links)
-3. `npm run seo:audit` (verify SEO front-matter)
+Two rules worth repeating here:
 
-For new doc pages, follow the front-matter pattern enforced by `scripts/audit-frontmatter.mjs` (title 25–60 chars, description 100–160 chars, keywords array).
+- **Verify before asserting.** Read the source for the signature, the default,
+  and the error message. Documented APIs that never existed have shipped before;
+  `npm run verify:api` exists to stop that.
+- **Moving or renaming a page requires a redirect** in `docusaurus.config.ts`.
 
 ## Related repos