diff --git a/apps/website/content/docs/langgraph/getting-started/installation.mdx b/apps/website/content/docs/langgraph/getting-started/installation.mdx index 879afb6d..6a32acac 100644 --- a/apps/website/content/docs/langgraph/getting-started/installation.mdx +++ b/apps/website/content/docs/langgraph/getting-started/installation.mdx @@ -12,7 +12,7 @@ Detailed setup guide for `injectAgent()` in your Angular application. Required for the build toolchain and package installation. -A running LangGraph agent accessible via HTTP. Can be local (langgraph dev) or deployed (LangGraph Cloud). +A running LangGraph agent reachable over HTTP. Local (`langgraph dev`) or deployed (LangGraph Cloud) both work. diff --git a/apps/website/content/docs/langgraph/getting-started/introduction.mdx b/apps/website/content/docs/langgraph/getting-started/introduction.mdx index 255895af..9bc0b713 100644 --- a/apps/website/content/docs/langgraph/getting-started/introduction.mdx +++ b/apps/website/content/docs/langgraph/getting-started/introduction.mdx @@ -1,8 +1,8 @@ # Introduction -> **Picking an adapter?** This guide covers `@threadplane/langgraph` — the LangChain/LangGraph adapter. If your backend speaks AG-UI protocol (CrewAI, Mastra, Microsoft Agent Framework, etc.), use [`@threadplane/ag-ui`](/ag-ui) instead. See [Choosing an adapter](/docs/choosing-an-adapter) for a side-by-side comparison. +> **Picking an adapter?** This guide covers `@threadplane/langgraph`, the LangChain/LangGraph adapter. If your backend speaks the AG-UI protocol (CrewAI, Mastra, Microsoft Agent Framework, and so on), reach for [`@threadplane/ag-ui`](/ag-ui) instead. [Choosing an adapter](/docs/choosing-an-adapter) puts them side by side. -`@threadplane/langgraph` is the Angular adapter layer for production-ready agent UI surfaces: chat, durable threads, interrupts, subagents, planning, memory, and generative UI. Build complete Angular 20+ agent applications with Signals, connect them to LangGraph agents, and keep the UI inside Angular templates, dependency injection, and your design system. +`@threadplane/langgraph` is the Angular adapter layer for production agent UI surfaces: chat, durable threads, interrupts, subagents, planning, memory, and generative UI. You build the whole Angular 20+ app with Signals, wire it to LangGraph agents, and keep the UI inside Angular templates, dependency injection, and your design system. This guide walks you through the complete workflow: build a LangGraph agent in Python, run it locally, connect it to an Angular app with `injectAgent()`, and deploy to production. diff --git a/apps/website/content/docs/langgraph/getting-started/quickstart.mdx b/apps/website/content/docs/langgraph/getting-started/quickstart.mdx index bafe7438..7d89624f 100644 --- a/apps/website/content/docs/langgraph/getting-started/quickstart.mdx +++ b/apps/website/content/docs/langgraph/getting-started/quickstart.mdx @@ -39,7 +39,7 @@ export const appConfig: ApplicationConfig = { -Use `injectAgent()` in a component field initializer. Every property on the returned ref is an Angular Signal. +Now let's wire up the UI. Call `injectAgent()` in a component field initializer — every property on the returned ref is an Angular Signal. diff --git a/docs/superpowers/plans/2026-06-05-docs-voice-langgraph-gs.md b/docs/superpowers/plans/2026-06-05-docs-voice-langgraph-gs.md new file mode 100644 index 00000000..a982f49e --- /dev/null +++ b/docs/superpowers/plans/2026-06-05-docs-voice-langgraph-gs.md @@ -0,0 +1,133 @@ +# Docs Voice Pass — LangGraph Getting Started — Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Surgically voice-edit the three LangGraph getting-started MDX pages into Brian's technical register — prose only, with code, commands, headings/anchors, and links left byte-identical. + +**Architecture:** Edit three MDX files in place. The control that keeps this safe is the **diff gate**: every change must be prose; nothing inside fenced code blocks, no command/API/version/link/heading text may change. + +**Tech Stack:** MDX docs (Next.js), `git diff` as the accuracy gate, Playwright/dev-server for render check. + +**Reference spec:** `docs/superpowers/specs/2026-06-05-docs-voice-langgraph-gs-design.md` +**Voice rubric:** `docs/gtm/voice.md` (technical register). + +--- + +## Voice rubric (apply surgically — don't churn in-voice prose) +- Title-as-lede (keep existing); contractions ("it's", "you'll", "let's"); one thought per line; short paragraphs. +- Quickstart: "Let's" lead-ins on steps where natural; a brief next-steps close if missing. +- Flag opinions ("For me", "In my experience") + a tradeoff — only where the page already recommends something. Don't invent opinions. +- Trim corporate stiffness/filler; concrete verbs. +- NO emojis, anecdotes, hype ("blazing", "game-changing", "powerful", "seamless"), or lecturing ("obviously"). + +## Hard guardrails (NON-NEGOTIABLE) +1. Never change anything inside a fenced ``` code block, nor any inline `code`, command, API name, type, version, or link/href. +2. Never change heading text (`#`/`##`/`###`) — `rehype-slug` anchors + the on-page TOC depend on it. The `# H1` titles stay exactly: "Introduction", "Quick Start", "Installation". +3. Preserve all MDX components (`Callout`, `Steps`, `Step`) and their props/attributes. +4. YAGNI — leave already-in-voice passages alone. If a page needs almost nothing, change almost nothing. +5. No technical corrections folded in. If you spot a real technical error, leave it and note it in your report (separate follow-up). + +--- + +## Task 1: Voice-edit the three pages + +**Files:** +- Modify: `apps/website/content/docs/langgraph/getting-started/introduction.mdx` +- Modify: `apps/website/content/docs/langgraph/getting-started/quickstart.mdx` +- Modify: `apps/website/content/docs/langgraph/getting-started/installation.mdx` + +- [ ] **Step 1: Read all three pages in full** + +```bash +cd /Users/blove/repos/angular-agent-framework +for f in introduction quickstart installation; do echo "===== $f ====="; cat "apps/website/content/docs/langgraph/getting-started/$f.mdx"; done +``` +Note where prose is stiff, where contractions are missing, where the quickstart could use a "Let's" lead-in or a next-steps close. Note every code block, command, heading, and link — those are off-limits. + +- [ ] **Step 2: Edit `introduction.mdx` (light touch)** + +Already strong (title-as-lede, "What you'll learn" callout, `## What is injectAgent()?`). Apply only: tighten any long/stiff sentences into one-thought-per-line, ensure contractions, make the adapter-picker blockquote read naturally. Keep ALL headings, the `injectAgent()` code block, the ``, and every link verbatim. + +- [ ] **Step 3: Edit `quickstart.mdx` (tutorial register)** + +Keep the ``/`` structure and EVERY command/code block verbatim. Apply: a natural "Let's" lead-in where a step introduction reads flatly; ensure a short **next-steps** close exists at the end (1–3 links onward to guides/concepts — reuse links already present elsewhere in the docs, e.g. `/docs/langgraph/guides/streaming`, `/docs/langgraph/concepts/agent-contract`; do not invent routes). Contractions throughout. Do not rename any `` (those render as headings/anchors-ish and are content) unless purely cosmetic and clearly better — default: keep. + +- [ ] **Step 4: Edit `installation.mdx` (tighten)** + +Keep the `` structure, all version requirements, and commands exactly. Tighten the requirement blurbs to one-thought-per-line; contractions. Keep headings. + +- [ ] **Step 5: Self-check the diff is prose-only** + +```bash +cd /Users/blove/repos/angular-agent-framework +git --no-pager diff apps/website/content/docs/langgraph/getting-started/ +``` +Verify by eye: every `+`/`-` pair is prose. NO changes inside ``` fences, NO changed commands/API names/versions/links, NO changed heading lines (`#`/`##`/`###`/``). If any code/heading/link line shows in the diff, revert that specific change. + +Automated guard — confirm headings and code fences are unchanged in count and text: +```bash +cd /Users/blove/repos/angular-agent-framework +for f in introduction quickstart installation; do + p="apps/website/content/docs/langgraph/getting-started/$f.mdx" + echo "== $f ==" + echo "headings:"; git --no-pager diff "$p" | grep -E "^[+-]\s*#{1,6} " || echo " (no heading lines changed — good)" + echo "code fences changed:"; git --no-pager diff "$p" | grep -E "^[+-]\s*\`\`\`" || echo " (no fence lines changed — good)" +done +``` +Expected: every line prints "(no … changed — good)". If a heading or fence line appears, fix it before committing. + +- [ ] **Step 6: Commit** + +```bash +cd /Users/blove/repos/angular-agent-framework +git add apps/website/content/docs/langgraph/getting-started/ +git commit -m "docs(langgraph): voice pass on getting-started pages" +``` +Do NOT stage `next-env.d.ts` / `tsconfig.tsbuildinfo`. + +- [ ] **Step 7: Report** + +Report what you changed per page (1–2 lines each), confirm the diff is prose-only (paste the heading/fence guard output), and flag any technical error you noticed but did NOT fix. + +--- + +## Task 2: Render verification + +**Files:** none (verification) + +- [ ] **Step 1: Serve + check the three pages render 200 with intact anchors** + +```bash +cd /Users/blove/repos/angular-agent-framework +lsof -ti tcp:3000 >/dev/null 2>&1 || (export PATH=/Users/blove/.nvm/versions/node/v22.14.0/bin:$PATH && npx nx serve website --port 3000 > /tmp/wd-voice.log 2>&1 &) +sleep 25 +for r in introduction quickstart installation; do + curl -s -o /dev/null -w "$r %{http_code}\n" "http://localhost:3000/docs/langgraph/getting-started/$r" +done +``` +Expected: all `200`. + +- [ ] **Step 2: Confirm headings/anchors unchanged vs main** + +```bash +cd /Users/blove/repos/angular-agent-framework +for f in introduction quickstart installation; do + p="apps/website/content/docs/langgraph/getting-started/$f.mdx" + diff <(git show origin/main:"$p" 2>/dev/null | grep -E "^#{1,6} ") <(grep -E "^#{1,6} " "$p") && echo "$f headings identical" || echo "$f HEADINGS CHANGED — investigate" +done +``` +Expected: "headings identical" for all three. + +(No e2e change needed — these routes already exist; the docs e2e and slug-page tests still cover rendering.) + +--- + +## Manual / reviewer verification (required before merge) +- [ ] **Accuracy diff review:** read the full `git diff` — confirm prose-only (no code/command/API/version/link/heading change). This is the gate. +- [ ] **Voice review:** each page reads in Brian's technical register (contractions, one-thought-per-line, quickstart has "Let's" + a next-steps close), with no emojis/hype/anecdotes. +- [ ] Pages render; anchors/TOC unchanged. + +## Self-Review (completed during planning) +- **Spec coverage:** all 3 pages (Task 1 steps 2-4) ✓; prose-only diff gate (Task 1 step 5 + Task 2 step 2) ✓; render check (Task 2 step 1) ✓; voice rubric + guardrails carried verbatim ✓; accuracy + voice review gate noted ✓. Out-of-scope (guides/concepts/reference, other libraries, technical fixes) excluded. +- **Placeholder scan:** No TBD/TODO. The prose edits are inherently author-judgment (a voice pass), but the rubric, the off-limits list, and the automated heading/fence guard make the boundaries exact; commands have expected output. +- **Consistency:** file paths consistent across tasks; the heading/fence guard in Task 1 step 5 and Task 2 step 2 use the same three files; "Quick Start" H1 preserved (matches docs-config title). diff --git a/docs/superpowers/specs/2026-06-05-docs-voice-langgraph-gs-design.md b/docs/superpowers/specs/2026-06-05-docs-voice-langgraph-gs-design.md new file mode 100644 index 00000000..fb44cb02 --- /dev/null +++ b/docs/superpowers/specs/2026-06-05-docs-voice-langgraph-gs-design.md @@ -0,0 +1,92 @@ +# Docs Voice Pass — LangGraph Getting Started — Design + +**Date:** 2026-06-05 +**Status:** Draft for review +**Scope:** A surgical voice pass over the three LangGraph getting-started pages, applying Brian's writing patterns (technical register) without changing any technical content. First batch of a multi-library getting-started voice pass. + +## Goal + +Bring the LangGraph onboarding pages fully into Brian's voice (technical +register) — the same rubric used for the a2ui pages — while leaving every +technical claim, code sample, command, and anchor intact. These pages are +already decent, so this is a **tightening pass**, not a rewrite. + +This is the first batch of the broader "voice pass over existing docs." Breadth +for the whole effort: **intros + getting-started pages only** (skip guides, +concepts, and API/reference). Each library is its own spec → plan cycle; +LangGraph is first. + +## Pages (3) + +- `apps/website/content/docs/langgraph/getting-started/introduction.mdx` +- `apps/website/content/docs/langgraph/getting-started/quickstart.mdx` +- `apps/website/content/docs/langgraph/getting-started/installation.mdx` + +## Voice rubric (technical register) + +Apply where it genuinely improves the page — surgical, not wholesale: + +- Title restated as a one-line lede (most pages already do this — keep it). +- Contractions natural ("it's", "you'll", "don't", "let's"). +- One thought per line; short paragraphs. +- Quickstart (tutorial): "Let's" transitions opening major steps where natural, + and a brief closing **next-steps / `## Conclusion`** if missing. +- Opinions flagged ("For me", "In my experience") and paired with a tradeoff — + only where the page actually makes a recommendation; don't manufacture + opinions. +- Trim corporate stiffness and filler; prefer the concrete verb. + +**Excluded:** no emojis, no anecdotes, no hype ("blazing", "game-changing", +"powerful", "seamless", "effortless"), no lecturing ("obviously"). + +## Hard guardrails (the risk in a voice pass) + +1. **Never change a technical claim, code snippet, shell command, API name, + type, version string, or link/href.** Voice = prose phrasing/structure only. +2. **Preserve heading text.** `rehype-slug` derives `#anchors` from heading + text; the on-page TOC and any deep links depend on them. Tighten body copy, + not section titles. (Decided default: keep headings stable. Rename a heading + only with explicit sign-off.) +3. Preserve all MDX components (`Callout`, `Steps`/`Step`, etc.), their props, + frontmatter conventions (these pages have none — title is the `# H1`), and + cross-links. +4. **YAGNI:** if a passage is already in-voice, leave it. Surgical edits beat + churn. The `# H1` titles ("Introduction", "Quick Start", "Installation") + stay — they map to nav/breadcrumb/anchors. + +## Per-page approach + +- **introduction.mdx** — already strong (title-as-lede, "What you'll learn" + callout, `## What is injectAgent()?` H2-as-question). Light touch: tighten any + long sentences, ensure contractions, confirm the adapter-picker note reads + naturally. Keep all headings + code. +- **quickstart.mdx** — tutorial register. Add "Let's" framing to step lead-ins + where natural; ensure a short next-steps close exists (link onward to the + guides/concepts). Keep the ``/`` structure, every command, and + the provider/config code verbatim. +- **installation.mdx** — reference-ish but onboarding. Tighten the requirement + blurbs; keep the `` structure, version requirements, and commands + exactly. + +## Testing & verification + +- **Accuracy diff gate (required):** for each page, the git diff must show + **prose-only** changes — no edits inside fenced code blocks, no changed + commands/API names/versions/links, no changed heading text or MDX component + props. A reviewer verifies the diff line-by-line. +- **Render:** each page returns HTTP 200 on the dev server and renders + unchanged structurally (same headings/anchors, same code blocks, same + callouts/steps). +- **Voice review:** each page checked against the rubric above. +- **Links/anchors:** confirm no in-page anchor changed (headings preserved) and + cross-links still resolve. + +## Out of scope + +- LangGraph guides, concepts, and API/reference pages (later, if at all — this + effort is getting-started only). +- Other libraries' getting-started (chat, render, ag-ui, a2ui[already in-voice], + licensing, telemetry) — each its own later batch. +- Any structural/navigation/component change; any technical correction (if a + real technical error is spotted, flag it separately — don't fold a content fix + into a voice edit).