docs: add ignite positioning and schema guidance (#88)

* docs: add ignite positioning and schema guidance

* chore(fas): record docs positioning task scope

* chore(fas): close docs positioning task

Author: 0xjcf

.fas/TASKS.md

@@ -1111,7 +1111,7 @@ No active tasks.
 
 - Title: Docs accuracy + UX + positioning for v3 beta.6 (P0/P1/P2). P0 (CORRECTNESS — beta.6 behavior change): the shared-source ownership fix in 3.0.0-beta.6 changed cleanup semantics but the docs-site prose still teaches the OLD beta.5 default. New behavior: cleanup defaults to FALSE for shared (consumer-owned) sources — a live instance passed to igniteCore (started actor / store / observable / actor-web source) lives for the core's lifetime and is NOT released when the element refcount hits zero; isolated (ignite-created) sources keep per-element teardown. Adapters never stop/close a source they did not create (generalized ownsActor -> ownsSource; ActorWebAdapter no longer closes consumer-owned sources). Update to the new semantics and drop now-redundant 'cleanup: false' guidance (reframe 'cleanup: true' as the opt-in to refcount teardown for shared cores) in: docs/site/src/content/docs/concepts/the-ignite-model.mdx (~17,45,225,226); docs/site/src/content/docs/api/ignite-core.mdx (~32,40,45); docs/site/src/content/docs/guides/routing.mdx (~165); docs/site/src/content/docs/migration/v2.mdx (~19,89,90,96); docs/site/src/content/docs/getting-started/first-component.mdx (~87); docs/site/src/content/docs/guides/testing.mdx (~135). DO NOT edit archived docs/site/src/content/docs/2.x/** (frozen). P1 (UX): add a /guides/ index landing page — currently 404 (Starlight has no guides index; individual guides are live, e.g. /guides/routing/ = 200); add a landing page linking the seven guides. P2 (positioning + agent angle): (a) add a 'When to choose Ignite / Comparisons' page surfacing existing positioning from /overview/what-is-ignite-element/ (distribution layer vs framework; renderer-agnostic; no state-lib lock-in); (b) deepen getSchema() docs with example output and how agents/LLMs consume it for tool-calling/validation. CONSTRAINTS: respect docs guardrails — markdownlint, the Playwright AA-contrast check (docs/site/scripts/check-contrast.mjs), and the doc code-example typecheck (check-doc-examples.mjs; object-form effects, no manual igniteCore<...> args); verify with the docs build. Source of truth for new behavior: packages/ignite-element/src/IgniteElementFactory.ts (cleanup default), packages/ignite-adapters/src/adapters/{XStateAdapter,ActorWebAdapter}.ts (ownsSource), and TSDoc on igniteCore/createIgniteComponentFactory.ts + igniteCore/types.ts.
 - Mode: 6-agent
-- Status: queued
+- Status: done
 - Owner: implementer
 - Brief: .fas/tasks/docs-accuracy-ux-positioning-for-v3-beta-6-p0-p1-p2-p.md
 - Verification lane: fast

.fas/queue/tasks.json

@@ -34,7 +34,7 @@
       "taskClassification": "self-improvement",
       "selfImprovementCategory": "policy-surfacing",
       "signalFingerprint": null,
-      "status": "deferred",
+      "status": "queued",
       "owner": "runtime",
       "mode": "single-agent",
       "dependsOn": [
@@ -48,33 +48,6 @@
       "prDependencies": [],
       "createdAt": "2026-06-12T19:30:13.064Z",
       "updatedAt": "2026-07-07T14:56:41.000Z",
-      "deferredReason": "dependency_reopened: task-1781724711926",
-      "invalidationReason": null
-    },
-    {
-      "id": "task-1781724711926",
-      "task": "Docs accuracy + UX + positioning for v3 beta.6 (P0/P1/P2). P0 (CORRECTNESS — beta.6 behavior change): the shared-source ownership fix in 3.0.0-beta.6 changed cleanup semantics but the docs-site prose still teaches the OLD beta.5 default. New behavior: cleanup defaults to FALSE for shared (consumer-owned) sources — a live instance passed to igniteCore (started actor / store / observable / actor-web source) lives for the core's lifetime and is NOT released when the element refcount hits zero; isolated (ignite-created) sources keep per-element teardown. Adapters never stop/close a source they did not create (generalized ownsActor -> ownsSource; ActorWebAdapter no longer closes consumer-owned sources). Update to the new semantics and drop now-redundant 'cleanup: false' guidance (reframe 'cleanup: true' as the opt-in to refcount teardown for shared cores) in: docs/site/src/content/docs/concepts/the-ignite-model.mdx (~17,45,225,226); docs/site/src/content/docs/api/ignite-core.mdx (~32,40,45); docs/site/src/content/docs/guides/routing.mdx (~165); docs/site/src/content/docs/migration/v2.mdx (~19,89,90,96); docs/site/src/content/docs/getting-started/first-component.mdx (~87); docs/site/src/content/docs/guides/testing.mdx (~135). DO NOT edit archived docs/site/src/content/docs/2.x/** (frozen). P1 (UX): add a /guides/ index landing page — currently 404 (Starlight has no guides index; individual guides are live, e.g. /guides/routing/ = 200); add a landing page linking the seven guides. P2 (positioning + agent angle): (a) add a 'When to choose Ignite / Comparisons' page surfacing existing positioning from /overview/what-is-ignite-element/ (distribution layer vs framework; renderer-agnostic; no state-lib lock-in); (b) deepen getSchema() docs with example output and how agents/LLMs consume it for tool-calling/validation. CONSTRAINTS: respect docs guardrails — markdownlint, the Playwright AA-contrast check (docs/site/scripts/check-contrast.mjs), and the doc code-example typecheck (check-doc-examples.mjs; object-form effects, no manual igniteCore<...> args); verify with the docs build. Source of truth for new behavior: packages/ignite-element/src/IgniteElementFactory.ts (cleanup default), packages/ignite-adapters/src/adapters/{XStateAdapter,ActorWebAdapter}.ts (ownsSource), and TSDoc on igniteCore/createIgniteComponentFactory.ts + igniteCore/types.ts.",
-      "priority": "high",
-      "source": "manual",
-      "details": "See .fas/tasks/docs-accuracy-ux-positioning-for-v3-beta-6-p0-p1-p2-p.md",
-      "taskClassification": "self-improvement",
-      "selfImprovementCategory": "runtime-reliability",
-      "signalFingerprint": null,
-      "status": "queued",
-      "owner": "runtime",
-      "mode": "6-agent",
-      "dependsOn": [
-        "task-1782187745669",
-        "task-1783357471256",
-        "task-1781818974159"
-      ],
-      "blocks": [
-        "task-1781292613064"
-      ],
-      "branchBase": null,
-      "prDependencies": [],
-      "createdAt": "2026-06-17T19:31:51.926Z",
-      "updatedAt": "2026-07-07T14:56:41.000Z",
       "deferredReason": null,
       "invalidationReason": null
     },
@@ -137,7 +110,7 @@
       "taskClassification": "self-improvement",
       "selfImprovementCategory": "developer-experience",
       "signalFingerprint": null,
-      "status": "deferred",
+      "status": "queued",
       "owner": "runtime",
       "mode": "single-agent",
       "dependsOn": [
@@ -150,7 +123,7 @@
       "prDependencies": [],
       "createdAt": "2026-06-18T17:54:22.589Z",
       "updatedAt": "2026-06-18T17:54:22.589Z",
-      "deferredReason": "dependency_reopened: task-1781724711926",
+      "deferredReason": null,
       "invalidationReason": null
     },
     {
@@ -2878,6 +2851,31 @@
       "workflowId": "direct-1783440023347",
       "branchName": "beta",
       "prStatus": "draft-only"
+    },
+    {
+      "id": "task-1781724711926",
+      "task": "Docs accuracy + UX + positioning for v3 beta.6 (P0/P1/P2). P0 (CORRECTNESS — beta.6 behavior change): the shared-source ownership fix in 3.0.0-beta.6 changed cleanup semantics but the docs-site prose still teaches the OLD beta.5 default. New behavior: cleanup defaults to FALSE for shared (consumer-owned) sources — a live instance passed to igniteCore (started actor / store / observable / actor-web source) lives for the core's lifetime and is NOT released when the element refcount hits zero; isolated (ignite-created) sources keep per-element teardown. Adapters never stop/close a source they did not create (generalized ownsActor -> ownsSource; ActorWebAdapter no longer closes consumer-owned sources). Update to the new semantics and drop now-redundant 'cleanup: false' guidance (reframe 'cleanup: true' as the opt-in to refcount teardown for shared cores) in: docs/site/src/content/docs/concepts/the-ignite-model.mdx (~17,45,225,226); docs/site/src/content/docs/api/ignite-core.mdx (~32,40,45); docs/site/src/content/docs/guides/routing.mdx (~165); docs/site/src/content/docs/migration/v2.mdx (~19,89,90,96); docs/site/src/content/docs/getting-started/first-component.mdx (~87); docs/site/src/content/docs/guides/testing.mdx (~135). DO NOT edit archived docs/site/src/content/docs/2.x/** (frozen). P1 (UX): add a /guides/ index landing page — currently 404 (Starlight has no guides index; individual guides are live, e.g. /guides/routing/ = 200); add a landing page linking the seven guides. P2 (positioning + agent angle): (a) add a 'When to choose Ignite / Comparisons' page surfacing existing positioning from /overview/what-is-ignite-element/ (distribution layer vs framework; renderer-agnostic; no state-lib lock-in); (b) deepen getSchema() docs with example output and how agents/LLMs consume it for tool-calling/validation. CONSTRAINTS: respect docs guardrails — markdownlint, the Playwright AA-contrast check (docs/site/scripts/check-contrast.mjs), and the doc code-example typecheck (check-doc-examples.mjs; object-form effects, no manual igniteCore<...> args); verify with the docs build. Source of truth for new behavior: packages/ignite-element/src/IgniteElementFactory.ts (cleanup default), packages/ignite-adapters/src/adapters/{XStateAdapter,ActorWebAdapter}.ts (ownsSource), and TSDoc on igniteCore/createIgniteComponentFactory.ts + igniteCore/types.ts.",
+      "priority": "high",
+      "source": "manual",
+      "taskClassification": "self-improvement",
+      "selfImprovementCategory": "runtime-reliability",
+      "signalFingerprint": null,
+      "dependsOn": [
+        "task-1782187745669",
+        "task-1783357471256",
+        "task-1781818974159"
+      ],
+      "blocks": [
+        "task-1781292613064"
+      ],
+      "branchBase": null,
+      "prDependencies": [],
+      "prRef": null,
+      "completedAt": "2026-07-07T20:26:55.486Z",
+      "terminalOutcome": null,
+      "workflowId": "direct-1783453213217",
+      "branchName": "fas/docs-accuracy-ux-positioning",
+      "prStatus": "draft-only"
     }
   ],
   "pullRequests": [],

.fas/tasks/docs-accuracy-ux-positioning-for-v3-beta-6-p0-p1-p2-p.md

@@ -4,17 +4,18 @@
 Created with `fas create-task` on 2026-06-17.
 
 ## Problem
-Docs accuracy + UX + positioning for v3 beta.6 (P0/P1/P2). P0 (CORRECTNESS — beta.6 behavior change): the shared-source ownership fix in 3.0.0-beta.6 changed cleanup semantics but the docs-site prose still teaches the OLD beta.5 default. New behavior: cleanup defaults to FALSE for shared (consumer-owned) sources — a live instance passed to igniteCore (started actor / store / observable / actor-web source) lives for the core's lifetime and is NOT released when the element refcount hits zero; isolated (ignite-created) sources keep per-element teardown. Adapters never stop/close a source they did not create (generalized ownsActor -> ownsSource; ActorWebAdapter no longer closes consumer-owned sources). Update to the new semantics and drop now-redundant 'cleanup: false' guidance (reframe 'cleanup: true' as the opt-in to refcount teardown for shared cores) in: docs/site/src/content/docs/concepts/the-ignite-model.mdx (~17,45,225,226); docs/site/src/content/docs/api/ignite-core.mdx (~32,40,45); docs/site/src/content/docs/guides/routing.mdx (~165); docs/site/src/content/docs/migration/v2.mdx (~19,89,90,96); docs/site/src/content/docs/getting-started/first-component.mdx (~87); docs/site/src/content/docs/guides/testing.mdx (~135). DO NOT edit archived docs/site/src/content/docs/2.x/** (frozen). P1 (UX): add a /guides/ index landing page — currently 404 (Starlight has no guides index; individual guides are live, e.g. /guides/routing/ = 200); add a landing page linking the seven guides. P2 (positioning + agent angle): (a) add a 'When to choose Ignite / Comparisons' page surfacing existing positioning from /overview/what-is-ignite-element/ (distribution layer vs framework; renderer-agnostic; no state-lib lock-in); (b) deepen getSchema() docs with example output and how agents/LLMs consume it for tool-calling/validation. CONSTRAINTS: respect docs guardrails — markdownlint, the Playwright AA-contrast check (docs/site/scripts/check-contrast.mjs), and the doc code-example typecheck (check-doc-examples.mjs; object-form effects, no manual igniteCore<...> args); verify with the docs build. Source of truth for new behavior: packages/ignite-element/src/IgniteElementFactory.ts (cleanup default), packages/ignite-adapters/src/adapters/{XStateAdapter,ActorWebAdapter}.ts (ownsSource), and TSDoc on igniteCore/createIgniteComponentFactory.ts + igniteCore/types.ts.
+Current HEAD already contains the beta.6 shared-source cleanup documentation and the /guides/ index. Complete the remaining docs-only P2 scope: add a dedicated overview page for “When to choose Ignite / Comparisons”, wire it into the sidebar and overview entry point, and deepen the agent-facing getSchema() documentation with concrete schema output plus tool-calling, validation, and canExecute guidance. Do not edit archived docs under docs/site/src/content/docs/2.x/**, runtime source, adapter source, test files, or docs scripts unless verification proves they are broken.
+
 
 ## Acceptance criteria
-- The new functionality works as described.
-- Existing behavior is not broken.
-- TDD: a failing test that captures the new or changed behavior is written before the implementation and lands in the same change.
-- TDD: every production code change in the change set is covered by an added or updated test.
-- DDD: respect domain boundaries — keep the functional core deterministic and side-effect-free (no reads, writes, network, or clock), confine coordination to the imperative shell, and have adapters return facts instead of throwing.
+- The new When to choose Ignite / Comparisons page exists under overview and is discoverable from the Overview sidebar.
+- The What is Ignite Element overview links readers to the new decision/comparison page.
+- The Headless runtime getSchema section includes concrete schema output and explains agent/LLM usage for tool selection, payload shaping, validation, canExecute checks, execute results, and observers.
+- Command metadata and Build for agents docs provide supporting links/context without duplicating the canonical getSchema contract.
+- Archived docs, runtime/source/adapter files, test files, and docs scripts remain untouched unless verification proves a defect.
+- Docs guardrails pass: markdownlint, docs code-example check, docs build, contrast check, and fas validate-task.
 - The work is tracked in `.fas/TASKS.md`.
 - The task has a clear implementation and verification plan before execution starts.
-- The task is queued in `.fas/queue/tasks.json` for the runtime.
 
 ## Proposed solution
 - Use the supplied problem context, acceptance criteria, and affected-file hints to draft the concrete implementation approach during planning.
@@ -23,18 +24,36 @@ Docs accuracy + UX + positioning for v3 beta.6 (P0/P1/P2). P0 (CORRECTNESS — b
 - None recorded at task creation. Add rejected approaches during planning if scope tradeoffs appear.
 
 ## Affected files
-- Scope unknown.
+- docs/site/src/content/docs/overview/when-to-choose-ignite.mdx
+- docs/site/src/content/docs/overview/what-is-ignite-element.mdx
+- docs/site/astro.config.mjs
+- docs/site/src/content/docs/api/headless-runtime.mdx
+- docs/site/src/content/docs/api/command-metadata.mdx
+- docs/site/src/content/docs/guides/agent-runtime-v3.mdx
 
 ## Scope Amendments
-- None.
+- Type: narrow-current-head-docs-scope
+- Added at: 2026-07-07
+- Trigger: Architect and staff handoffs found stale generated commit plan after PR87 merged.
+- Reason: The original task included P0 cleanup docs and P1 guides index work already present in current HEAD; remaining work is P2 docs positioning and agent-facing getSchema guidance.
+- Added paths: docs/site/src/content/docs/overview/when-to-choose-ignite.mdx, docs/site/src/content/docs/overview/what-is-ignite-element.mdx, docs/site/astro.config.mjs, docs/site/src/content/docs/api/headless-runtime.mdx, docs/site/src/content/docs/api/command-metadata.mdx, docs/site/src/content/docs/guides/agent-runtime-v3.mdx
+- Evidence source: fas_architect and fas_staff_engineer handoffs
+- Evidence: fas_architect and fas_staff_engineer handoffs | .fas/state/commit-plan.json | Generated plan targeted packages/ignite-element/src/tests/IgniteCore.test.ts and docs/site/scripts/check-contrast.mjs, while actual remaining scope is docs content/sidebar files.
+- Accuracy signal: Current docs contain beta.6 cleanup semantics and docs/site/src/content/docs/guides/index.mdx exists.
+- Follow-up needed: Regenerate active task scope and commit plan before spawning fas_senior_engineer.
 
 ## Implementation plan
-- Convert the supplied context into a scoped implementation plan before editing.
-- Refresh affected-file scope before implementation if the generated hints are incomplete.
+- Add a dedicated overview/when-to-choose-ignite.mdx comparisons page focused on decision criteria and positioning.
+- Add sidebar discoverability and a concise link from the existing overview page.
+- Deepen the canonical getSchema() docs and supporting agent-runtime/command-metadata pages without duplicating runtime contracts.
 
 ## Verification plan
-- Run `fas validate-task` for the inner-loop verification gate.
-- Run `.fas/scripts/verify.sh --full` at the final release-quality gate when tracked files change.
+- fas validate-task
+- pnpm lint:md
+- pnpm --filter docs-site run check:docs
+- pnpm --filter docs-site run check:contrast
+- pnpm docs:build
+- .fas/scripts/verify.sh --full at branch closeout
 
 ## Risks
 - Validate generated scope, acceptance criteria, and verification evidence before closeout to avoid workflow drift.

docs/site/astro.config.mjs

@@ -61,6 +61,10 @@ export default defineConfig({
 							label: "What is Ignite Element?",
 							slug: "overview/what-is-ignite-element",
 						},
+						{
+							label: "When to choose Ignite",
+							slug: "overview/when-to-choose-ignite",
+						},
 					],
 				},
 				{

docs/site/src/content/docs/api/command-metadata.mdx

@@ -95,6 +95,8 @@ The predicate function is not serialized into `getSchema()`. Instead the schema
 marks the command with `gated: true`, and consumers call
 `runtime.canExecute('submit')` for the current answer.
 
+That split keeps `getSchema()` JSON-serializable for agents and tool providers while leaving the current availability check in the live runtime. See the richer [`getSchema()` walkthrough](/ignite-element/api/headless-runtime/#getschema) for the full read -> gate -> execute flow.
+
 ## In `getSchema()`
 
 Once commands carry metadata, `getSchema()` returns executable commands and their metadata in one map. Commands without metadata appear as empty objects: