Skip to main content

Docs launch readiness — what should be there before we press go

The docs/ Docusaurus site exists and builds, but it's contributor- facing only (design notes, investigation logs, two node-family reference pages) and isn't linked from anywhere — no CI publish step, no pointer from the main app or its README. This page is the plan for what needs to be true before we treat it as a real, public-facing docs site with a user guide and screenshots, prompted by the getting-started page being the first piece of genuinely end-user content added.

Status (October 2026)​

Done: the site builds clean with broken links as errors; the deploy target is Cloudflare Pages at edgeweave.app (.github/workflows/docs.yml); the node reference is generated from node metadata and a test keeps it current; the user guide now covers getting started, projects and files, packages, Python export, the scheduler, the marketplace, loops, subsystems, five feature tutorials and troubleshooting. Still open: screenshots (section 2; the landing page already uses Playwright captures from scripts/site_capture), a CI drift check for node names mentioned in prose (section 3), and a link from the repo README (section 4).

Why not now​

The UI is still moving. The Ctrl+K palette and the error-highlighting fix both landed within the last day (main, PR #28), and there's an open, unconfirmed bug from that same work (a node getting stuck in the "active" highlight state — see the error-highlight-and-node- palette history). A screenshot-heavy user guide written against the UI at this exact commit has a short shelf life. Narrow, stable pieces (like the palette shortcut) are safe to document now; a full click-through guide isn't yet.

What "ready" looks like​

0. npm run build needs to actually succeed — done (v0.4 prep)​

Update: the merge-conflict blocks were resolved in favour of the "resolved" side (bundling has shipped since v0.3), the MDX escape fixed, a / → /intro redirect added and onBrokenLinks set to 'throw'; npm run build is clean. The user guide (Getting Started + five tutorials) now exists and is shown offline on the app's Docs screen. Still open: a public deploy target (section 1) and real screenshots (the tutorials mark where they go).

Original note:

Right now it doesn't: docs/docs/electron-build-fix.md has four unresolved git-merge-conflict blocks (<<<<<<< HEAD / ======= / >>>>>>> main) checked into the file, and docs/docs/python-electron- bundling.md has an unescaped <1 MB in a markdown table that MDX parses as a JSX tag. Confirmed via git stash that this predates this round of changes — verified the getting-started and launch- readiness pages themselves compile and link correctly by building with those two files temporarily moved aside. The MDX-escaping fix is mechanical, but resolving the merge-conflict content needs a human call: the two sides disagree on whether Bug 4 (Python/backend bundling) is resolved or still deferred, and the linked python-electron-bundling.md checklist itself is half-checked (Windows steps done, macOS/Linux/smoke-test not) — so "which version is current" isn't something to guess at from the doc content alone. Flagged as a follow-up rather than fixed inline here.

1. A deploy target is chosen​

docusaurus.config.js currently has placeholder url, organizationName, and projectName values and onBrokenLinks: 'warn' (not 'throw'). Before launch:

  • Pick a host (GitHub Pages via npm run deploy is the path of least resistance given docusaurus deploy is already wired up in package.json; an internal server is the alternative if the docs shouldn't be public).
  • Fill in the real url/organizationName/projectName.
  • Flip onBrokenLinks to 'throw' so a broken internal link fails CI instead of shipping silently.

2. Screenshot capture is automated, but gated, not blind​

Proposal: a Playwright script that drives the packaged app (or the Vite dev server) against a small set of fixed seed .weave files — not the developer's live workspace, so output is deterministic — and writes PNGs into docs/static/img/.

  • Trigger: manual dispatch or a scheduled CI job, not every commit. UI screenshots break in visually-subtle ways (a moved toolbar, a palette-width change) that a diff tool flags but a human should confirm before it overwrites a published image.

    Concretely: a re-run job produces new candidate screenshots and a visual diff (e.g. pixel-diff against the previous committed image) as a CI artifact or PR; a person approves before merge. Nothing auto-publishes.
  • Seed data: a handful of small .weave files checked into the screenshot script's fixtures dir, chosen to be boring and stable (a few nodes, no node names or values likely to change soon).
  • Scope for v1: cover exactly the surfaces the getting-started guide will reference — sidebar drag, Ctrl+K palette open/search, a completed run with the green/red highlight states. Don't try to screenshot everything; grow it alongside the guide.

3. A drift check for prose, not just images​

Full accuracy-checking of prose isn't realistically automatable, but the most common failure mode — a doc referencing a node, flag, or endpoint that no longer exists — is. Proposal: a CI script that extracts node-name references from the docs (e.g. anything in backtick-code matching a known node-id pattern) and cross-checks them against the live registry via /api/nodes (backend/fastapi_main.py) or the backend's node-loading path (backend/core/module_loader.py). Fails CI on a reference to a node that no longer exists. This is a canary for structural drift, not a guarantee the surrounding prose is still correct — that still needs a human pass periodically.

4. The site is actually linked somewhere​

Once 1–3 are in place: a build/deploy step in CI, and a link from the main repo README (or the app itself, e.g. a "Docs" item in an Electron menu) pointing at the published URL. Tracked as the same follow-up already flagged in the docs backlog.

5. A real "how to use EdgeWeave" guide​

Only after the above: expand past getting-started into full coverage — wiring nodes together, running a graph, saving/ loading projects, the code editor, the chat assistant. This is the part most worth deferring until the UI has had a stable stretch, since it's the highest-cost content to keep in sync.

Suggested order of work​

  1. Pick + configure the deploy target (cheap, unblocks everything downstream, no dependency on UI stability).
  2. Build the screenshot script against today's UI, scoped to just the getting-started surfaces, human-reviewed before first publish.
  3. Add the node-reference drift check to CI.
  4. Link the site from the README.
  5. Revisit once there's been a quiet stretch (no palette/canvas UI changes for a couple of weeks, say) and expand into the full guide.

Open questions​

  • Public (GitHub Pages) or internal hosting? Affects whether screenshots/content need any redaction review.
  • Who owns approving screenshot diffs — is that a step in the normal PR review, or a separate periodic pass?