Docs: AEO Tier 2 — canonical answer pages (what-is, comparisons, FAQ, no-code guide) (#96)

* Docs: AEO Tier 2 canonical answer pages (what-is, comparisons, FAQ, etc.)

Adds the eight canonical answer pages from AEO_PLAN.md Tier 2 so the docs
own the high-intent queries an evaluator asks an AI assistant about Squadron.
Every page has a query-shaped H1 and a definition-first opening paragraph so
answer engines can extract a clean response.

New pages:
- /what-is-squadron — definition-first, with a competitor table
- /compare/{langgraph,crewai,autogen,n8n} — honest head-to-head with
  side-by-side code, "when to pick X" sections, and migration notes
- /no-code-multi-agent-workflow — full walkthrough building a scheduled
  daily-brief mission, HCL-vs-Python angle throughout
- /declarative-ai-agent-framework — category-defining page with the
  imperative-vs-declarative analysis and nine evaluation properties
- /faq — 20 questions covering price, license, providers, on-prem,
  MCP, resume, plugins, comparisons. FAQPage JSON-LD inlined with all
  20 entries for answer-engine consumption.

Nav: docs/content/_meta.js gets the new top-level entries and a "Compare"
section. compare/_meta.js orders the four comparisons.

Generator improvements (docs/scripts/generate-llms.mjs):
- Strips MDX-only syntax ({/* */} comments and inline <script> /
  self-closing <script ... /> blocks) before parsing summaries and writing
  raw .md mirrors. This keeps llms.txt summaries clean even on pages that
  inline JSON-LD payloads.

AEO_PLAN.md: Tier 2 boxes checked.

* Docs/compare: expand plugin treatment — Go/Python plugins are the primary extension primitive, MCP is complementary

Each comparison page now has a dedicated "Extension model" section that
treats Squadron plugins as the first-class extension primitive they
actually are: standalone Go or Python programs that the runtime spawns
as subprocesses over gRPC (hashicorp/go-plugin), auto-built from local
source with content-hash caching, stateful across tasks, and
distributable via GitHub releases. MCP is positioned as complementary
— good for integrations someone else already built, while plugins
cover the integrations you build yourself.

Updates:
- compare/langgraph.mdx — contrasts plugin subprocess isolation with
  LangGraph tools as Python functions in the same process
- compare/crewai.mdx — contrasts language choice and auto-build vs
  CrewAI's Python BaseTool class model
- compare/autogen.mdx — contrasts cross-task plugin state and process
  isolation with AutoGen's in-process Python function tools
- compare/n8n.mdx — contrasts plugin authoring effort (single Go or
  Python file, auto-built) with n8n's TypeScript community-node SDK,
  while acknowledging n8n's strength in pre-built SaaS coverage

Also updates each TL;DR table's tool-ecosystem row to be more accurate.

* Docs: reorganize nav with Learn/Build/Reference/Evaluate separators

The Tier 2 AEO pages were grafted onto the existing nav and the seams
showed: Introduction and "What is Squadron?" duplicated, "Advanced" was
a one-page section, and the new evaluator pages (Compare, FAQ, No-Code
Guide, Declarative Framework) sat in a grab-bag at the bottom.

This commit reorganizes the nav into four funnel-stage groups using
Nextra v4 separator entries, without changing any AEO-critical URL.

Changes:
- Top-level docs/content/_meta.js now uses { type: 'separator', title }
  entries to group sidebar items as Learn / Build / Reference / Evaluate.
- index.mdx is now a short docs home (~50 lines): one-paragraph
  definition, one code example, three labeled CTA blocks routing new
  visitors / builders / evaluators to the right next page. Long-form
  definitional content stays at /what-is-squadron where it belongs.
- docs/content/advanced/distributing-plugins.mdx →
  docs/content/guides/distributing-plugins.mdx
- docs/content/no-code-multi-agent-workflow.mdx →
  docs/content/guides/no-code-multi-agent-workflow.mdx
- docs/content/advanced/ removed (no other pages there).
- docs/content/guides/_meta.js created with two entries.
- Internal link in config/plugins.mdx updated to the new guides/ path.

Generator improvements (docs/scripts/generate-llms.mjs):
- Treat { type: 'separator', title } _meta.js entries as section
  headers in llms.txt, so the new Learn/Build/Reference/Evaluate
  groupings show up there too.
- Prune stale .md mirrors from public/ when a content file is moved or
  removed. Without this, renaming a page leaves a ghost mirror that
  ships to production until someone notices.

URL preservation: every page from PR #95 (Tier 1 AEO plumbing) keeps
its current URL. The only moved URLs are /no-code-multi-agent-workflow
and /advanced/distributing-plugins, both of which were added in the
still-open Tier 2 PR and never deployed.

DOCS_NAV_PLAN.md captures the design and execution.

* Docs: merge What is Squadron? into Introduction

The two pages had too much crossover — same definition, same code
example, same "that's the whole workflow" line. Maintaining both was
duplicate effort and confusing in the nav.

This commit consolidates everything onto the docs root (/). The
merged page is substantially what /what-is-squadron was: definition,
problem framing, two-tier execution model, what's included, when to
use it / when not, comparison table, and three labeled CTA blocks at
the end (new visitors, builders, evaluators).

Changes:
- docs/content/index.mdx absorbs the long-form content of
  what-is-squadron.mdx and keeps the CTA structure.
- docs/content/what-is-squadron.mdx deleted.
- docs/content/_meta.js drops the what-is-squadron entry.
- All internal references to /what-is-squadron updated to / across:
  faq.mdx, declarative-ai-agent-framework.mdx, compare/*.mdx, and
  guides/no-code-multi-agent-workflow.mdx.

The /what-is-squadron URL was added in this unmerged PR and never
deployed, so no external link breaks. The home page now serves the
same content the URL was promising.

AEO impact: minimal. The "what is squadron" query is now answered by
the docs root, which carries the entire site's authority and is the
URL most likely to be linked externally. The page's H1 "Squadron" plus
the prominent "What problem does Squadron solve?" H2 give answer
engines a strong signal that this is the canonical definition page.

* Docs: rename "Declarative AI Agent Framework" → "Declarative Agent Framework"

Tightens the category name. "AI agent framework" is redundant — agent
frameworks in this category are AI agent frameworks by definition.

Changes:
- File: declarative-ai-agent-framework.mdx → declarative-agent-framework.mdx
- URL : /declarative-ai-agent-framework → /declarative-agent-framework
- Title and H1 in the page itself
- Body text using the phrase as a category name
- Generic phrase "Most AI agent frameworks today are imperative" →
  "Most agent frameworks today are imperative" for consistency
- Internal links updated in _meta.js, index.mdx, and
  guides/no-code-multi-agent-workflow.mdx

Unchanged: literal example values like topic = "AI agent frameworks"
inside HCL code blocks (those are placeholder topic strings, not
category names).

Author: mlund01

AEO_PLAN.md

@@ -18,11 +18,11 @@ Ordered by impact-per-effort. Tier 1 first.
 
 Title + H1 must echo the query verbatim. Answer engines extract the first paragraph when the H1 matches.
 
-- [ ] **6. "What is Squadron?"** — one-paragraph definition first, then features.
-- [ ] **7. Comparison pages**: "Squadron vs LangGraph", "Squadron vs CrewAI", "Squadron vs AutoGen", "Squadron vs n8n". Honest comparison tables.
-- [ ] **8. "How to build a multi-agent workflow without writing code"** — long-form, HCL-vs-Python angle.
-- [ ] **9. "Declarative AI agent framework"** — own the category name.
-- [ ] **10. FAQ page** with 15–20 high-intent questions (pricing, license, providers, on-prem, resume, state model, MCP, plugin languages). Each Q as `<h3>` in natural phrasing.
+- [x] **6. "What is Squadron?"** — [`docs/content/what-is-squadron.mdx`](docs/content/what-is-squadron.mdx). Definition-first, includes feature summary and competitor comparison table.
+- [x] **7. Comparison pages**: [`compare/langgraph`](docs/content/compare/langgraph.mdx), [`crewai`](docs/content/compare/crewai.mdx), [`autogen`](docs/content/compare/autogen.mdx), [`n8n`](docs/content/compare/n8n.mdx). Honest tradeoffs, side-by-side code, "when to pick X" sections.
+- [x] **8. "How to build a multi-agent workflow without writing code"** — [`docs/content/no-code-multi-agent-workflow.mdx`](docs/content/no-code-multi-agent-workflow.mdx). Full walkthrough of a daily-brief mission, HCL-vs-Python angle throughout.
+- [x] **9. "Declarative AI agent framework"** — [`docs/content/declarative-ai-agent-framework.mdx`](docs/content/declarative-ai-agent-framework.mdx). Category-defining page with imperative-vs-declarative analysis.
+- [x] **10. FAQ page** — [`docs/content/faq.mdx`](docs/content/faq.mdx). 20 questions covering pricing, license, providers, on-prem, MCP, resume, plugins, comparisons. FAQPage JSON-LD inlined for answer engines.
 
 ## Tier 3 — Off-site signal
 

DOCS_NAV_PLAN.md

@@ -0,0 +1,163 @@
+# Docs Reorganization Plan (executed)
+
+**Status:** Shipped on the same branch as Tier 2 (PR #96). All bullets below describe the executed end state — see commits on `claude/aeo-tier-2-content`.
+
+---
+
+
+
+The Tier 2 AEO pages were grafted onto the existing nav and the seams show. This plan reorganizes the docs so visitors find a coherent path, without breaking any AEO-critical URLs.
+
+---
+
+## What's wrong now
+
+Current top-level nav (after Tier 2):
+
+```
+Introduction
+What is Squadron?
+Getting Started
+CLI Commands
+Configuration
+Missions
+Advanced
+Compare
+No-Code Guide
+Declarative Framework
+FAQ
+```
+
+Problems:
+
+1. **Introduction and What is Squadron? duplicate.** Both define the product. A first-time visitor doesn't know which to read; both have a definitional opening.
+2. **AEO landing pages are interleaved with reference docs.** "No-Code Guide" lives between "Compare" and "Declarative Framework", which sits next to "FAQ". Each is good on its own, but as a list they read as a grab-bag.
+3. **"Advanced" is one page.** It currently holds only [Distributing Plugins](docs/content/advanced/distributing-plugins.mdx). A single-page section is noise in the nav.
+4. **No funnel-stage groupings.** Someone evaluating Squadron (Compare, FAQ) is reading the same nav as someone deep in build mode (Configuration, Missions). The nav doesn't signal which sections to read in which order.
+5. **The Harness page is buried in Missions.** [`missions/harness`](docs/content/missions/harness.mdx) is a conceptual explainer about the runtime model — closer in kind to "What is Squadron?" than to "Tasks" or "Routing". Its current placement makes it easy to miss for evaluators.
+
+## Goals
+
+- Visitors land on a coherent first page. No duplicate "what is this" pages staring at each other in the nav.
+- Evaluator content (what-is, comparisons, FAQ, declarative-framework) is grouped together and discoverable, but not interleaved with reference docs.
+- Builder content (missions, config, CLI, guides) is grouped together.
+- **No AEO-critical URLs change.** Pages already in [llms.txt](docs/public/llms.txt), [sitemap.xml](docs/public/sitemap.xml), and the [Tier 2 PR description](https://github.com/mlund01/squadron/pull/96) must keep their current paths. Any reorg happens through `_meta.js`, not file moves.
+- Nav uses **section separators** so groupings are visible without nesting URLs (which would change paths).
+
+## Proposed top-level nav
+
+Nextra v4 supports separator entries in `_meta.js` of the form `{ type: 'separator', title: '...' }`. Use them to create visual section headings in the sidebar without altering URLs.
+
+```
+LEARN
+├── Introduction              # short docs home — routes to evaluator + builder paths
+├── What is Squadron?         # canonical definitional answer page
+├── Declarative Framework     # category-defining conceptual page
+└── Getting Started/          # install, quickstart, docker
+
+BUILD
+├── Missions/                 # overview, harness, tasks, routing, iteration, datasets, folders, schedules, budgets, internal-tools
+├── Configuration/            # variables, models, agents, skills, tools, functions, plugins, mcp, gateways, command_center
+└── Guides
+    ├── No-Code Multi-Agent Workflow   # currently /no-code-multi-agent-workflow
+    └── Distributing Plugins           # currently /advanced/distributing-plugins
+
+REFERENCE
+└── CLI Reference/            # rename "CLI Commands"
+
+EVALUATE
+├── Compare/                  # 4 vs pages
+└── FAQ
+```
+
+### What changes mechanically
+
+| Concern | Action |
+|---|---|
+| Section headings | Add `{ type: 'separator', title: 'Learn' }`-style entries to top-level `_meta.js`. |
+| Rename "CLI Commands" → "CLI Reference" | Label change in `_meta.js` only. URL `/cli/...` unchanged. |
+| Fold "Advanced" into Guides | Move `distributing-plugins.mdx` from `content/advanced/` into a new `content/guides/` directory. **This changes its URL** — see URL-preservation section. |
+| Promote "The Harness" | Add a top-level alias to it from the Learn section in nav, or rewrite the Introduction page so it links prominently. Don't move the file. |
+| Group `no-code-multi-agent-workflow` and the moved-`distributing-plugins` into a new "Guides" bucket | Either (a) leave file at top level and have nav say "Guides" as a separator that contains the single page link, or (b) move into `content/guides/` directory. Option (b) is cleaner but changes the URL. |
+| De-duplicate Introduction and What is Squadron? | Rewrite `index.mdx` to be a short docs home (3 paragraphs + 4 CTA cards). All definitional content lives at `/what-is-squadron`. |
+
+### URL preservation
+
+These URLs must NOT change (they're in `llms.txt`, `sitemap.xml`, the FAQPage JSON-LD, internal cross-links, and the merged PR #95):
+
+- `/`
+- `/what-is-squadron`
+- `/declarative-ai-agent-framework`
+- `/no-code-multi-agent-workflow`
+- `/faq`
+- `/compare/{langgraph,crewai,autogen,n8n}`
+- `/getting-started/{installation,quickstart,docker}`
+- `/cli/{quickstart,engage,disengage,verify,chat,mission,vars,upgrade}`
+- `/config/*` (all current files)
+- `/missions/*` (all current files)
+
+URLs we **could** change (recent, not yet externally shared):
+
+- `/advanced/distributing-plugins` — only one inbound external link risk; safe to move
+
+Recommendation: leave **all** AEO and reference URLs alone. Use `_meta.js` separators for the nav structure. The one optional move is `advanced/distributing-plugins` → `guides/distributing-plugins`, which we can ship with a Next.js redirect to keep the old URL alive.
+
+### Content changes (no URL impact)
+
+1. **Rewrite [`index.mdx`](docs/content/index.mdx) as a short docs home.** Target: ~25 lines. One opening paragraph, four CTA cards (What is Squadron? / Quick Start / Missions / Compare), and a single short code example. Move the long-form "what is / how it works / what's in the box" content into [`what-is-squadron.mdx`](docs/content/what-is-squadron.mdx), which already has most of it.
+2. **Promote [`The Harness`](docs/content/missions/harness.mdx) into the Learn section** without moving the file — add it to top-level `_meta.js` (Nextra supports this; a key like `'missions/harness'` in the parent meta references the nested file). If that's not possible, link to it prominently from `what-is-squadron.mdx`.
+3. **Add a short paragraph cross-reference** at the top of [`declarative-ai-agent-framework.mdx`](docs/content/declarative-ai-agent-framework.mdx) and [`what-is-squadron.mdx`](docs/content/what-is-squadron.mdx) pointing to each other and to the FAQ, so the three landing pages function as a cohesive set.
+4. **Move [`advanced/distributing-plugins.mdx`](docs/content/advanced/distributing-plugins.mdx) to `guides/`** and add a redirect from `/advanced/distributing-plugins` to `/guides/distributing-plugins`. Delete the empty `advanced/` directory.
+
+## Final proposed `docs/content/_meta.js`
+
+```js
+export default {
+  '__learn': { type: 'separator', title: 'Learn' },
+  index: 'Introduction',
+  'what-is-squadron': 'What is Squadron?',
+  'declarative-ai-agent-framework': 'Declarative Framework',
+  'getting-started': 'Getting Started',
+
+  '__build': { type: 'separator', title: 'Build' },
+  missions: 'Missions',
+  config: 'Configuration',
+  guides: 'Guides',
+
+  '__reference': { type: 'separator', title: 'Reference' },
+  cli: 'CLI Reference',
+
+  '__evaluate': { type: 'separator', title: 'Evaluate' },
+  compare: 'Compare',
+  faq: 'FAQ',
+
+  // The 'no-code-multi-agent-workflow' page becomes guides/no-code-multi-agent-workflow.mdx
+  // (folded into the Guides directory). Its URL changes; add a redirect from the old path.
+  // Alternatively keep top-level and remove from guides/ — see open decision below.
+}
+```
+
+## Open decisions
+
+1. **Should `no-code-multi-agent-workflow` keep its top-level URL or move under `/guides/`?** Top-level is better for AEO (shorter URL, "guides" prefix is forgettable). But then Guides is a one-item directory (only distributing-plugins). Recommendation: **keep at top level, list in nav under the Guides separator without nesting the URL**. This requires referencing the file from a parent `_meta.js` — Nextra supports cross-directory references in `_meta.js` via the same key syntax used for nested directories.
+2. **Do we want a `/concepts/` directory?** Folding what-is-squadron, declarative-ai-agent-framework, and the harness under `/concepts/` would be conceptually clean — but it changes URLs. **Recommendation: no, keep all at top level.** Use the Learn separator for nav grouping only.
+3. **How short should the new Introduction page be?** Recommendation: 25–40 lines. Definition + 4 CTA cards + one example. All long-form content lives at `/what-is-squadron`.
+4. **Do we keep "Advanced" as an empty bucket for future use?** Recommendation: **no, delete it.** It signals nothing meaningful. Re-introduce later if we have ≥3 advanced pages.
+
+## Migration sequence
+
+1. Verify Nextra v4 separator syntax in this codebase (one quick test in a feature branch).
+2. Rewrite `index.mdx` to be a short docs home — move detail into `what-is-squadron.mdx` where it already lives.
+3. Move `advanced/distributing-plugins.mdx` → `guides/distributing-plugins.mdx`. Add Next.js redirect for the old URL.
+4. Update `docs/content/_meta.js` with the new separator-based structure.
+5. Add cross-references between the three Learn-section landing pages.
+6. Regenerate `llms.txt` (the generator already picks up the file moves automatically).
+7. Build, click through every section heading, verify all URLs in the URL-preservation list still resolve.
+8. Open PR with screenshots of before/after nav.
+
+## What this does *not* do
+
+- Doesn't change page content beyond `index.mdx` shortening and small cross-reference links.
+- Doesn't add new AEO pages (those continue in Tier 3+).
+- Doesn't reorganize per-section `_meta.js` within Configuration or Missions — those are well-ordered already.
+- Doesn't break any URL that appears in `llms.txt`, `sitemap.xml`, the FAQPage JSON-LD, or external references.

docs/content/_meta.js

@@ -1,8 +1,18 @@
 export default {
+  '__learn': { type: 'separator', title: 'Learn' },
   index: 'Introduction',
+  'declarative-agent-framework': 'Declarative Framework',
   'getting-started': 'Getting Started',
-  cli: 'CLI Commands',
-  config: 'Configuration',
+
+  '__build': { type: 'separator', title: 'Build' },
   missions: 'Missions',
-  advanced: 'Advanced',
+  config: 'Configuration',
+  guides: 'Guides',
+
+  '__reference': { type: 'separator', title: 'Reference' },
+  cli: 'CLI Reference',
+
+  '__evaluate': { type: 'separator', title: 'Evaluate' },
+  compare: 'Compare',
+  faq: 'FAQ',
 }

docs/content/compare/_meta.js

@@ -0,0 +1,6 @@
+export default {
+  langgraph: 'vs LangGraph',
+  crewai: 'vs CrewAI',
+  autogen: 'vs AutoGen',
+  n8n: 'vs n8n',
+}