diff --git a/.github/workflows/verify.yml b/.github/workflows/verify.yml
new file mode 100644
index 0000000..26ced76
--- /dev/null
+++ b/.github/workflows/verify.yml
@@ -0,0 +1,15 @@
+name: Verify
+
+on:
+ pull_request:
+ push:
+ branches: [main]
+
+jobs:
+ roadmap-check:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: marlinjai/actions-shared/roadmap-check@roadmap-check-v1
+ with:
+ max-age: 30
diff --git a/ROADMAP.md b/ROADMAP.md
index 7e05c6d..99378fd 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -147,7 +147,6 @@ Replaced `@scalar/api-reference-react` with a fully custom-built renderer using
- [x] Admin panel for visual config editing (Phases 1-3 of `2026-03-09-visual-config-editing-design.md`)
- [x] Split config into machine-writable data layer (JSON) and code layer (TS)
- [x] Manage hub projects, sections, and settings without hand-editing `clearify.config.ts`
-- [ ] Phase 4 (git-gateway for deployed sites): out of scope
## v1.13: README Auto-Inclusion
@@ -179,91 +178,100 @@ Replaced `@scalar/api-reference-react` with a fully custom-built renderer using
## v2.0 — Try It Out & Auth (OpenAPI Phase 2-3)
### API Playground
-- [ ] `TryItPanel` inside `OperationCard` — toggled by "Try It" button
-- [ ] Auto-generated forms from operation parameter + request body schemas
-- [ ] Configurable proxy URL (`openapi.proxyUrl` config option)
-- [ ] Response display with status code, headers, syntax-highlighted body
+- [ ] `TryItPanel` inside `OperationCard` — toggled by "Try It" button See [plan](docs/plans/2026-03-08-openapi-auth-ui-design.md). (2026-09-10)
+- [ ] Auto-generated forms from operation parameter + request body schemas (2026-09-10)
+- [ ] Configurable proxy URL (`openapi.proxyUrl` config option) (2026-09-10)
+- [ ] Response display with status code, headers, syntax-highlighted body (2026-09-10)
### Auth Management
-- [ ] `AuthManager` — persistent panel reading `components.securitySchemes`
-- [ ] Bearer token input, API key input, OAuth2 flow
-- [ ] Auth state injected into Try It requests and code examples
-- [ ] Server selector dropdown (from `spec.servers[]`)
+- [ ] `AuthManager` — persistent panel reading `components.securitySchemes` (2026-09-10)
+- [ ] Bearer token input, API key input, OAuth2 flow (2026-09-10)
+- [ ] Auth state injected into Try It requests and code examples (2026-09-10)
+- [ ] Server selector dropdown (from `spec.servers[]`) (2026-09-10)
## v2.1 — Power Features
### API Documentation (Advanced)
- [x] SDK code example generation (cURL, Python, JS) — built into v1.6 custom renderer
- [x] Request/response schema display with nested types — built into v1.6 SchemaViewer
-- [ ] API playground — interactive request builder (planned for v1.9)
### Content Management
- [x] Multi-section support — pill-based section switcher (Guides / Internal / etc.)
- [x] Unified `docs/public/` + `docs/internal/` folder structure
- [x] Draft sections excluded from production builds
- [x] `clearify init --no-internal` flag
-- [ ] Versioned docs — version switcher, separate content per version
-- [ ] Reusable snippets — define once, `` anywhere
-- [ ] Conditional content — show/hide based on context (version, audience)
-- [ ] Dropdown menus in header navigation
+- [ ] Versioned docs — version switcher, separate content per version See [plan](docs/plans/2026-03-08-versioned-docs-architecture.md). (2026-09-10)
+- [ ] Reusable snippets — define once, `` anywhere (2026-09-10)
+- [ ] Conditional content — show/hide based on context (version, audience) (2026-09-10)
+- [ ] Dropdown menus in header navigation (2026-09-10)
### Search & Discovery
- [x] Keyboard navigation in search results (arrow keys + Enter)
- [x] Section-scoped search result badges
-- [ ] Search analytics — track what users search for
+- [ ] Search analytics — track what users search for (2026-09-10)
- [x] `llms.txt` auto-generation for AI discoverability
### Analytics
-- [ ] Page view tracking (pluggable: Plausible, Umami, PostHog)
-- [ ] Inline feedback widget (thumbs up/down per page)
-- [ ] Popular pages dashboard
+- [ ] Page view tracking (pluggable: Plausible, Umami, PostHog) (2026-09-10)
+- [ ] Inline feedback widget (thumbs up/down per page) (2026-09-10)
+- [ ] Popular pages dashboard (2026-09-10)
## v2.5 — In-Place Editing
> See [2026-03-03-in-place-editing-plan.md](../plans/2026-03-03-in-place-editing-plan.md) for full architecture
### Phase 1: Local Dev Editing (quick win)
-- [ ] `POST /__clearify/save` endpoint on dev server — writes to `.md` file, Vite HMR reloads
-- [ ] Editor overlay component (CodeMirror split pane: source + live preview)
-- [ ] Floating "Edit" button on each page in dev mode
-- [ ] `editing.dev` config option
+- [ ] `POST /__clearify/save` endpoint on dev server — writes to `.md` file, Vite HMR reloads See [plan](docs/plans/2026-03-03-in-place-editing-plan.md). (2026-09-10)
+- [ ] Editor overlay component (CodeMirror split pane: source + live preview) (2026-09-10)
+- [ ] Floating "Edit" button on each page in dev mode (2026-09-10)
+- [ ] `editing.dev` config option (2026-09-10)
### Phase 2: Git-Backed Production Editing
-- [ ] GitHub OAuth flow for authentication
-- [ ] Save-to-GitHub via Contents API (browser → GitHub directly, no Clearify backend)
-- [ ] `editing.provider: 'github'` config with repo, branch, mode (direct commit or PR)
-- [ ] Remote section awareness — edits to embedded docs target the source repo
-- [ ] "Saved — rebuilding..." UI with commit link
-- [ ] Works with every deployment target (static site unchanged)
+- [ ] GitHub OAuth flow for authentication (2026-09-10)
+- [ ] Save-to-GitHub via Contents API (browser → GitHub directly, no Clearify backend) (2026-09-10)
+- [ ] `editing.provider: 'github'` config with repo, branch, mode (direct commit or PR) (2026-09-10)
+- [ ] Remote section awareness — edits to embedded docs target the source repo (2026-09-10)
+- [ ] "Saved — rebuilding..." UI with commit link (2026-09-10)
+- [ ] Works with every deployment target (static site unchanged) (2026-09-10)
### Phase 3: Instant Preview Layer (premium, only if demand warrants)
-- [ ] Worker middleware (`@marlinjai/clearify-edge`) in front of static assets
-- [ ] Save drafts to Cloudflare KV (~5ms) for instant visibility
-- [ ] Async git commit + rebuild in background
-- [ ] KV cleanup after successful rebuild (TTL-based)
-- [ ] Server-side markdown rendering at the edge
-- [ ] Conflict resolution for concurrent edits
+- [ ] Worker middleware (`@marlinjai/clearify-edge`) in front of static assets See [plan](docs/plans/2026-03-08-edge-preview-layer-design.md). (2026-09-10)
+- [ ] Save drafts to Cloudflare KV (~5ms) for instant visibility (2026-09-10)
+- [ ] Async git commit + rebuild in background (2026-09-10)
+- [ ] KV cleanup after successful rebuild (TTL-based) (2026-09-10)
+- [ ] Server-side markdown rendering at the edge (2026-09-10)
+- [ ] Conflict resolution for concurrent edits (2026-09-10)
**Why Phase 3 is different:** It transforms Clearify from a build tool into a runtime platform. The deployed site is no longer purely static — a Worker serves dynamic content from KV while git catches up. Only build this when instant editing becomes a real user demand.
## v3.0 — AI-Native & Ecosystem
### AI Features
-- [ ] AI chat over docs — RAG-powered Q&A widget
-- [ ] AI-generated summaries per page
-- [ ] MCP server — expose docs to AI agents
-- [ ] Markdown export endpoint for LLM consumption
+- [ ] AI chat over docs — RAG-powered Q&A widget See [plan](docs/plans/2026-03-08-ai-integration-design.md). (2026-09-10)
+- [ ] AI-generated summaries per page (2026-09-10)
+- [ ] MCP server — expose docs to AI agents (2026-09-10)
+- [ ] Markdown export endpoint for LLM consumption (2026-09-10)
### i18n
-- [ ] Multi-language support with language switcher
-- [ ] Per-language navigation and content
-- [ ] RTL layout support (Arabic, Hebrew)
+- [ ] Multi-language support with language switcher (2026-09-10)
+- [ ] Per-language navigation and content (2026-09-10)
+- [ ] RTL layout support (Arabic, Hebrew) (2026-09-10)
### Ecosystem
-- [ ] Plugin system (extend build pipeline, add custom transforms)
-- [ ] Community themes (swap default theme)
-- [ ] Monorepo support (multiple doc sites from one repo)
-- [ ] Migration tools (import from Mintlify, Docusaurus, GitBook)
+- [ ] Plugin system (extend build pipeline, add custom transforms) See [plan](docs/plans/2026-03-08-plugin-system-design.md). (2026-09-10)
+- [ ] Community themes (swap default theme) (2026-09-10)
+- [ ] Monorepo support (multiple doc sites from one repo) (2026-09-10)
+- [ ] Migration tools (import from Mintlify, Docusaurus, GitBook) (2026-09-10)
+
+## Deferred — linked plans, not yet scheduled
+
+- [ ] Decide the disposition of branch `wip/hub-paths-reports-2026-04-18` (still present on
+ origin): it preserves 4 hub-model report files from 2026-04-18 that were accidentally bundled
+ into the vocabulary pull request and stripped back out. Keep as-is, turn into a proper pull
+ request, or drop the branch. Marlin's call. (2026-09-10)
+
+- [ ] Bring the Clearify Pages deployments under Terraform (Cloudflare Pages project + domain + DNS + HUB_DISPATCH_TOKEN + API tokens via Infisical), the last piece of Marlin's stack not in the infra repo. See [plan](docs/plans/2026-04-19-clearify-iac-alignment.md). (2026-09-10)
+- [ ] Visual diagram editor: an interactive ReactFlow-based diagram/whiteboard editor with dev-server write-back to source markdown. See [plan](docs/plans/2026-03-01-visual-diagram-editor-plan.md). (2026-09-10)
## Out of Scope
diff --git a/package.json b/package.json
index f93ae83..58c06de 100644
--- a/package.json
+++ b/package.json
@@ -32,7 +32,8 @@
"dev:self": "node bin/clearify.js dev",
"prepare": "husky",
"release": "semantic-release",
- "test": "vitest run"
+ "test": "vitest run",
+ "check:roadmap": "npx --yes github:marlinjai/actions-shared#roadmap-check-v1 --root ."
},
"dependencies": {
"@inquirer/password": "^5.0.11",