From 80a7e054989bc799d736c9cd3d193f5d1cfb771a Mon Sep 17 00:00:00 2001 From: Marlin Date: Thu, 10 Sep 2026 16:12:13 +0200 Subject: [PATCH] chore(roadmap): adopt roadmap-check, date and link the roadmap pile Work-down session 9b (framer-clone + clearify plan reconciliation) of the one-home-per-open-item plan. clearify is dormant (no commits since 2026-06-07), so this is reconciliation only, no product work. - roadmap-check added as a new verify.yml workflow (max-age 30) and wired into package.json as check:roadmap. - 45 open checkbox lines re-read and re-dated (2026-09-10): all are live, unshipped v2.0+ roadmap items (checked against package.json version 2.1.0 and a source-tree grep for each named feature; none were secretly already built). - 2 lines deleted as not wanted (listed below, per the plan's contract). - 8 previously-unlinked draft plans (144 to 193 days old) now linked from an open roadmap line each, so roadmap-check can see they are still wanted: openapi-auth-ui-design, versioned-docs-architecture, edge-preview-layer-design, ai-integration-design, plugin-system-design, in-place-editing-plan (the v2.5 section already carried a prose pointer to it; added to an actual open line so the checker counts it), clearify-iac-alignment and visual-diagram-editor-plan (neither had any roadmap section at all; both are now under a new "Deferred" heading). - 1 more HOMED line added under the same "Deferred" heading: the wip/hub-paths-reports-2026-04-18 branch disposition from this session's own backlog note (branch decisions are Marlin's, not executed here). Deleted lines (not re-added; not wanted): - "Phase 4 (git-gateway for deployed sites): out of scope" -- the line's own text says it is out of scope, so it is not an open item. - "API playground -- interactive request builder (planned for v1.9)" under v2.1 Power Features -- a stale duplicate of the full "API Playground" section already tracked under v2.0 (same feature, same plan link). Local check: "46 open lines, 8 linked plans, 14 plan files scanned, no drift" Co-Authored-By: Claude Sonnet 5 --- .github/workflows/verify.yml | 15 ++++++ ROADMAP.md | 98 +++++++++++++++++++----------------- package.json | 3 +- 3 files changed, 70 insertions(+), 46 deletions(-) create mode 100644 .github/workflows/verify.yml 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",