From e4f1ec87ddec14597c245b02a40798ae87333d3b Mon Sep 17 00:00:00 2001 From: philipheider-libra Date: Fri, 28 Aug 2026 15:12:08 +0200 Subject: [PATCH 1/2] docs: initial Libra SDK site Guides, getting-started, reference and capabilities pages for @libra/sdk, generated changelog + version snippet (synced to v0.13.0), structural check script, Playwright capture harness and CI workflow. Co-Authored-By: Claude Fable 5 --- .claude/skills/sdk-docs-update/SKILL.md | 95 ++ .github/workflows/check.yml | 14 + .gitignore | 6 + .mintignore | 16 +- .nvmrc | 1 + AGENTS.md | 33 - CLAUDE.md | 76 ++ README.md | 63 +- Screenshots/.gitignore | 6 + Screenshots/README.md | 62 + Screenshots/auth/.env.example | 5 + Screenshots/manifest/shots.yaml | 113 ++ Screenshots/manifest/storyboards.yaml | 38 + Screenshots/package-lock.json | 1586 +++++++++++++++++++++++ Screenshots/package.json | 30 + Screenshots/src/actions.ts | 38 + Screenshots/src/auth.ts | 33 + Screenshots/src/capture.ts | 39 + Screenshots/src/cli.ts | 55 + Screenshots/src/compose.ts | 64 + Screenshots/src/frame.ts | 11 + Screenshots/src/liveclip.ts | 68 + Screenshots/src/overlay.ts | 41 + Screenshots/src/paths.ts | 28 + Screenshots/src/render.ts | 37 + Screenshots/src/runner.ts | 87 ++ Screenshots/src/sample_frames.ts | 28 + Screenshots/src/storyboard.ts | 75 ++ Screenshots/src/types.ts | 53 + Screenshots/src/visual_check.ts | 91 ++ Screenshots/tsconfig.json | 16 + capabilities/chat.mdx | 98 ++ capabilities/context-and-sources.mdx | 101 ++ capabilities/overview.mdx | 63 + capabilities/plans-and-limits.mdx | 61 + capabilities/products-and-sources.mdx | 57 + changelog.mdx | 180 +++ docs.json | 138 +- favicon.svg | 8 +- getting-started/how-it-works.mdx | 58 + getting-started/playground.mdx | 33 + getting-started/quickstart.mdx | 109 ++ guides/authentication.mdx | 82 ++ guides/best-practices.mdx | 57 + guides/chat-handoff.mdx | 36 + guides/citations.mdx | 50 + guides/document-suggestions.mdx | 76 ++ guides/embedding.mdx | 108 ++ guides/installation.mdx | 63 + guides/locales.mdx | 82 ++ guides/panel-and-placement.mdx | 95 ++ guides/proxy-mode.mdx | 185 +++ guides/security-headers.mdx | 35 + index.mdx | 59 +- logo/dark.svg | 17 - logo/light.svg | 17 - quickstart.mdx | 47 - reference/api.mdx | 114 ++ reference/types.mdx | 131 ++ scripts/check.mjs | 63 + scripts/release-scan.mjs | 106 ++ scripts/sync-changelog.mjs | 108 ++ snippets/sdk-version.mdx | 3 + 63 files changed, 5115 insertions(+), 233 deletions(-) create mode 100644 .claude/skills/sdk-docs-update/SKILL.md create mode 100644 .github/workflows/check.yml create mode 100644 .gitignore create mode 100644 .nvmrc delete mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 Screenshots/.gitignore create mode 100644 Screenshots/README.md create mode 100644 Screenshots/auth/.env.example create mode 100644 Screenshots/manifest/shots.yaml create mode 100644 Screenshots/manifest/storyboards.yaml create mode 100644 Screenshots/package-lock.json create mode 100644 Screenshots/package.json create mode 100644 Screenshots/src/actions.ts create mode 100644 Screenshots/src/auth.ts create mode 100644 Screenshots/src/capture.ts create mode 100644 Screenshots/src/cli.ts create mode 100644 Screenshots/src/compose.ts create mode 100644 Screenshots/src/frame.ts create mode 100644 Screenshots/src/liveclip.ts create mode 100644 Screenshots/src/overlay.ts create mode 100644 Screenshots/src/paths.ts create mode 100644 Screenshots/src/render.ts create mode 100644 Screenshots/src/runner.ts create mode 100644 Screenshots/src/sample_frames.ts create mode 100644 Screenshots/src/storyboard.ts create mode 100644 Screenshots/src/types.ts create mode 100644 Screenshots/src/visual_check.ts create mode 100644 Screenshots/tsconfig.json create mode 100644 capabilities/chat.mdx create mode 100644 capabilities/context-and-sources.mdx create mode 100644 capabilities/overview.mdx create mode 100644 capabilities/plans-and-limits.mdx create mode 100644 capabilities/products-and-sources.mdx create mode 100644 changelog.mdx create mode 100644 getting-started/how-it-works.mdx create mode 100644 getting-started/playground.mdx create mode 100644 getting-started/quickstart.mdx create mode 100644 guides/authentication.mdx create mode 100644 guides/best-practices.mdx create mode 100644 guides/chat-handoff.mdx create mode 100644 guides/citations.mdx create mode 100644 guides/document-suggestions.mdx create mode 100644 guides/embedding.mdx create mode 100644 guides/installation.mdx create mode 100644 guides/locales.mdx create mode 100644 guides/panel-and-placement.mdx create mode 100644 guides/proxy-mode.mdx create mode 100644 guides/security-headers.mdx delete mode 100644 logo/dark.svg delete mode 100644 logo/light.svg delete mode 100644 quickstart.mdx create mode 100644 reference/api.mdx create mode 100644 reference/types.mdx create mode 100644 scripts/check.mjs create mode 100644 scripts/release-scan.mjs create mode 100644 scripts/sync-changelog.mjs create mode 100644 snippets/sdk-version.mdx diff --git a/.claude/skills/sdk-docs-update/SKILL.md b/.claude/skills/sdk-docs-update/SKILL.md new file mode 100644 index 0000000..01c9917 --- /dev/null +++ b/.claude/skills/sdk-docs-update/SKILL.md @@ -0,0 +1,95 @@ +--- +name: sdk-docs-update +description: Release-driven update of the Libra SDK docs. Scans what shipped in @libra/sdk (LibratechAI/sandbox packages/sdk) since the docs' synced version, regenerates the changelog, updates the affected pages from the SDK README, refreshes the screenshots/videos those pages use, runs the structural and visual gates, and opens a PR. Use when the user says "update the SDK docs", "what shipped in the SDK", "sync the SDK changelog", or a new SDK version is out. +--- + +# SDK docs update + +One pass per release (or batch of releases): **scan → sync changelog → update pages → capture/render assets → check → PR.** Everything derives from `LibratechAI/sandbox` `packages/sdk/` (`README.md` = API contract, `CHANGELOG.md` = what shipped). Read [CLAUDE.md](../../../CLAUDE.md) first for the source-of-truth and page conventions. + +## Prerequisites + +- `gh auth status` OK (the sandbox is private). Node 22 on PATH (`/opt/homebrew/opt/node@22/bin`). +- `Screenshots/node_modules` installed and `npx playwright install chromium` done (see [Screenshots/README.md](../../../Screenshots/README.md)). +- For `auth: true` captures: a fresh `Screenshots/auth/storageState.json` — `cd Screenshots && npm run auth`. **This is the only manual gate**; skip it when no page needs new authenticated shots. + +## Steps + +### 1. Scan +```bash +git checkout main && git pull +node scripts/release-scan.mjs # releases newer than snippets/sdk-version.mdx, bullets bucketed by page, merged SDK PRs +``` +`Nothing new` → stop. Otherwise note every version, every **BREAKING** bullet, and the **Unreleased** block (merged, not shipped: never document it). + +### 1b. Never document a claim you have not checked against the code + +The SDK README and the WK product decks both go stale. On 2026-08-27 a 13-topic verification pass over the "SDK v2" deck returned 74 findings: only 11 CONFIRMED, 13 outright OUTDATED, 47 partly wrong. Things that would have shipped as fact: a `622px` breakpoint that exists nowhere in the codebase, Deep Thinking described as a paid-tier feature (it is not gated at all), and a chat-mode selector that is now a combined tier+model control. + +So, for any claim sourced from a deck, a ticket, a Slack message, or the README rather than from code you just read: + +- Verify it against `LibratechAI/sandbox` `main` before it reaches a page. `gh api "repos/LibratechAI/sandbox/git/trees/main?recursive=1" --jq '.tree[].path'` then read the files. +- Separate **SDK-package behaviour** (`packages/sdk/`) from **main-app behaviour rendered inside the iframe** (`src/`). They have different release cycles and the distinction changes what an integrator can rely on. +- Treat flag-gated or entitlement-gated behaviour as **not general**. If it sits behind a feature flag, a per-team grant, or an env var, either say so explicitly or leave it out. +- Never publish: internal flag names, M2M credentials, unreleased work, or the ops mechanics behind a restriction. +- Attribute design guidance that is not in the code as guidance ("Wolters Kluwer design guidance, not enforced by the SDK"). + +For a batch of claims this is worth fanning out — one agent per topic, each returning `{claim, verdict, evidence, corrected, docsRelevance}`, with a second agent adversarially re-checking every CONFIRMED/OUTDATED verdict. The adversarial pass is what caught the flag-gating and the SDK-vs-app confusions above. + +### 2. Diff the contract +The changelog says *what* changed; the README says *how it now works*. Pull the README changes in the window and read them: +```bash +gh api "repos/LibratechAI/sandbox/commits?path=packages/sdk/README.md&since=T00:00:00Z" --jq '.[].sha' \ + | xargs -I{} gh api repos/LibratechAI/sandbox/commits/{} --jq '.files[] | select(.filename=="packages/sdk/README.md") | .patch' +``` +For bullets the scan could not bucket, `gh pr view <#> --repo LibratechAI/sandbox` on the listed PRs. + +### 3. Sync the changelog +```bash +git checkout -b docs/sdk-v +node scripts/sync-changelog.mjs # rewrites changelog.mdx + snippets/sdk-version.mdx +git add changelog.mdx snippets && git commit -m "changelog: sync to v" +``` + +### 4. Update pages +For each `## By docs page` bucket from step 1: +- **README text or snippet changed** → update the page; code that exists in the README is copied verbatim, not paraphrased. `grep -rn "" --include=*.mdx .` to catch every occurrence of a renamed option/slug/type. +- **New `init()` option or `Libra.*` method** → `reference/api.mdx` (table/section) + the guide that owns the behaviour + `reference/types.mdx` if a type changed. +- **New product/source/locale** → `capabilities/products-and-sources.mdx` or `guides/locales.mdx`, and the type unions in `reference/types.mdx`. +- **BREAKING** → make sure the migration is stated on the affected page (old → new) in addition to the tagged changelog entry. +- **Pure UI change** (no API) → `capabilities/overview.mdx` prose if a user would notice; otherwise changelog only. +- **New page** → add it to `docs.json` navigation and to `PAGE_MAP` in `scripts/release-scan.mjs`. + +Internal-only detail (SPEC.md internals, M2M credentials, roadmap, security specifics) never goes in. Keep content commits separate from asset commits. + +### 5. Assets for changed pages +For every page edited in step 4, list its images/videos and its TODO markers: +```bash +grep -oE '(src="/assets/[^"]+"|TODO (screenshot|video): [a-z0-9-]+)' .mdx +``` +- **Existing shot whose UI changed** → `cd Screenshots && npm run capture -- --id `; fix selectors in `manifest/shots.yaml` if the playground moved (prefer ids/roles/text; `host:` for host-page controls). +- **New shot** → add a manifest entry (unique `id`, `output: assets/images/sdk/-.png`, `page:`), put `{/* TODO screenshot: */}` where the image goes, capture, then replace the marker with `…`. +- **Videos** → `npm run render -- --id ` (composed from stills by default); replace `{/* TODO video: */}` with the `