docs: add docs.page validation gate and newcomer onboarding

.github/workflows/ci.yml

@@ -15,9 +15,20 @@ jobs:
     timeout-minutes: 25
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
 
-      - uses: subosito/flutter-action@v2
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
+        with:
+          node-version: "20"
+
+      - uses: pnpm/action-setup@f40ffcd9367d9f12939873eb1018b921a783ffaa
+        with:
+          version: 9.15.4
+
+      - name: pnpm install (docs.page CLI)
+        run: pnpm install --frozen-lockfile
+
+      - uses: subosito/flutter-action@1a449444c387b1966244ae4d4f8c696479add0b2
         with:
           channel: stable
           cache: true
@@ -36,3 +47,6 @@ jobs:
 
       - name: pub.dev dry-run (all packages)
         run: dart run tool/intentcall/bin/intentcall.dart publish-all
+
+      - name: docs.page check
+        run: pnpm run docs:check

.github/workflows/pub_publish.yml

@@ -7,7 +7,7 @@ on:
   workflow_dispatch:
     inputs:
       tag:
-        description: 'Release tag to preflight, for example intentcall_core-v0.1.1'
+        description: 'Release tag to preflight, for example intentcall_core-v0.2.1'
         required: true
         type: string
 
@@ -27,14 +27,14 @@ jobs:
     env:
       RELEASE_TAG: ${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.ref_name }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
 
-      - uses: subosito/flutter-action@v2
+      - uses: subosito/flutter-action@1a449444c387b1966244ae4d4f8c696479add0b2
         with:
           channel: stable
           cache: true
 
-      - uses: dart-lang/setup-dart@v1
+      - uses: dart-lang/setup-dart@65eb853c7ba17dde3be364c3d2858773e7144260
 
       - name: Workspace dependencies
         run: dart pub get

.github/workflows/release-please.yml

@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Release Please
-        uses: googleapis/release-please-action@v4
+        uses: googleapis/release-please-action@8b8fd2cc23b2e18957157a9d923d75aa0c6f6ad5
         with:
           token: ${{ secrets.RELEASE_PLEASE_TOKEN || secrets.GITHUB_TOKEN }}
           config-file: release-please-config.json

.gitignore

@@ -9,3 +9,5 @@ build/
 *.iml
 .flutter-plugins
 .flutter-plugins-dependencies
+node_modules/
+package-lock.json

AGENTS.md

@@ -1,6 +1,9 @@
 # IntentCall — Agent Map
 
-IntentCall is a **transport-agnostic agent intent platform** for Dart/Flutter.
+**IntentCall** lets Dart/Flutter apps define agent-callable actions once in `AgentRegistry`, then project them to MCP, WebMCP, shortcuts, and deep links — without rewriting per transport. **Building a Flutter app?** Start with [mcp_flutter](https://github.com/Arenukvern/mcp_flutter). **Building adapters or platform projection?** You're in the right repo.
+
+Published docs: [docs.page/Arenukvern/intentcall](https://docs.page/Arenukvern/intentcall) · Full router: [docs/start_here/docs_map.mdx](docs/start_here/docs_map.mdx)
+
 Install Skill Steward meta-skills for this repo:
 
 ```bash

CONTRIBUTING.md

@@ -7,6 +7,7 @@ Thanks for your interest! IntentCall is a pre-release platform library. Contribu
 - [Dart SDK](https://dart.dev/get-dart) `^3.11.0`
 - [Flutter SDK](https://flutter.dev/docs/get-started/install) (stable) — required for `intentcall_platform`
 - [just](https://github.com/casey/just) task runner (recommended)
+- [Node.js](https://nodejs.org/) `>=18` and [pnpm](https://pnpm.io/) `>=9` — for `just docs-check` (docs.page link validation)
 
 ## Quick start
 
@@ -19,7 +20,12 @@ just analyze     # static analysis
 just publish-dry-run  # pub.dev validation (no credentials needed)
 ```
 
-All three must be green before opening a PR.
+All three must be green before opening a PR. If you changed `docs/` or `docs.json`, also run:
+
+```bash
+pnpm install   # once
+just docs-check
+```
 
 ## Conventional commits
 
@@ -44,8 +50,8 @@ See [docs/DX_FAQ.mdx](docs/DX_FAQ.mdx) — "How do I add a new `intentcall_*` pa
 
 ## Publishing
 
-Publishing to pub.dev is maintainer-gated. Maintainers run `just publish-preflight-first` for the first publish, `just publish-preflight` for later releases, then `just publish-dry-run` before `just publish-execute`. See [PUBLISHING.md](PUBLISHING.md).
+Publishing to pub.dev is maintainer-gated. Maintainers normally merge the Release Please PR and let tag-triggered GitHub Actions publish through pub.dev automated publishing. `just publish-dry-run` and tag dry-runs are preflight checks; manual execute commands are recovery-only. See [PUBLISHING.md](PUBLISHING.md).
 
 ## Pre-release note
 
-All packages are `0.1.x`. APIs may change without a semver major. See [PRE_RELEASE.md](PRE_RELEASE.md).
+All packages are `0.2.x` train. APIs may change without a semver major. See [PRE_RELEASE.md](PRE_RELEASE.md).

PRE_RELEASE.md

@@ -1,9 +1,9 @@
 # Pre-release notice (all intentcall packages)
 
-**Status:** Pre-release `0.1.x` — not production-ready.
+**Status:** Pre-release `0.2.x` train — not production-ready.
 
 - APIs are **highly experimental** and may change without a major semver bump.
-- Breaking changes can land in any `0.1.x` patch while the design stabilizes.
+- Breaking changes can land in any `0.2.x` train patch while the design stabilizes.
 - Standalone repo at [github.com/Arenukvern/intentcall](https://github.com/Arenukvern/intentcall) (sibling to `mcp_flutter` locally).
 - Prefer **path** or **pinned git refs** for dogfood; use pub.dev only after explicit release notes.
 

PUBLISHING.md

@@ -1,8 +1,9 @@
 # Publishing intentcall to pub.dev
 
-Status: `0.1.0` has been published to pub.dev for the `intentcall_*`
-package train. Use this runbook for future releases; keep the first-publish
-checks only as historical/diagnostic guidance.
+Status: the current published train is `0.2.x`; all publishable
+`intentcall_*` packages should move together. Use this runbook for normal
+tag-triggered releases; keep first-publish and manual execute commands only as
+historical or recovery guidance.
 
 ## Automatic release and publish flow
 
@@ -16,7 +17,7 @@ publishing:
    into one package train, including `intentcall_session`, so versions remain
    synchronized.
 4. Merging the release PR creates component tags such as
-   `intentcall_core-v0.1.1`.
+   `intentcall_core-v0.2.1`.
 5. `.github/workflows/pub_publish.yml` runs for each `intentcall_*-v*` tag and
    publishes the package named by that tag. The workflow is skip-existing safe,
    so rerunning a tag does not republish an already visible package version.
@@ -87,24 +88,24 @@ just publish-preflight
 just publish-dry-run
 
 # Validate one package tag the way automated publishing does
-just publish-tag-dry-run intentcall_session-v0.1.0
+just publish-tag-dry-run intentcall_session-v0.2.1
 
 # Diagnostic only while release-critical files are dirty; still fails archive/content errors
 just publish-dry-run-ignore-warnings
 
-# After credentials are configured
+# Recovery-only: after credentials are configured and automated publishing is unavailable
 just publish-execute
 
 # CI normally runs this from .github/workflows/pub_publish.yml on tag push
-just publish-tag-execute intentcall_session-v0.1.0
+just publish-tag-execute intentcall_session-v0.2.1
 ```
 
 For a brand-new package name, treat `just publish-preflight-first` as the release desk:
 
 - All `intentcall_*` package names must report available on pub.dev.
 - The release-critical tree must be clean: publishable `packages/intentcall_*` files plus `tool/intentcall`, including newly added public API files such as `packages/intentcall_core/lib/intentcall_core_migration.dart`.
 - `dart pub token list` must show a configured token for pub.dev.
-- `just publish-dry-run` must pass from the same clean release commit before `just publish-execute`.
+- `just publish-dry-run` must pass from the same clean release commit before any recovery manual publish.
 
 `just publish-dry-run-ignore-warnings` is only for diagnosing archive/content issues before the release-critical tree is clean. It must not replace the strict dry-run above.
 
@@ -119,7 +120,7 @@ cd packages/intentcall_platform && flutter pub publish --dry-run
 
 ## After publish (mcp_flutter cutover)
 
-Status: the initial `0.1.0` hosted cutover is complete in `mcp_flutter`.
+Status: the initial hosted cutover is complete in `mcp_flutter`.
 For future IntentCall releases, update consumers only after the pub.dev package
 pages exist for the full publish order above.
 

README.md

@@ -2,13 +2,13 @@
 
 [![maintained with Skill Steward](https://raw.githubusercontent.com/Arenukvern/skill_steward/main/docs/brand/assets/svg/badge-solid.svg)](https://github.com/Arenukvern/skill_steward)
 
-> **Pre-release (`0.1.x`)** — Highly experimental. APIs may change without notice. **Not for production.** See [PRE_RELEASE.md](PRE_RELEASE.md).
+> **Pre-release (`0.2.x` train)** — Highly experimental. APIs may change without notice. **Not for production.** See [PRE_RELEASE.md](PRE_RELEASE.md).
 
 *Register intents. Call them everywhere.*
 
-Transport-agnostic agent intent platform for Dart/Flutter: define intent truth once in `AgentRegistry`, then project it into the strongest available surface: MCP/WebMCP, native semantic action systems where supported, assistant/shortcut fulfillment, and canonical deep-link fallback where native support is incomplete. Extracted from [mcp_flutter](https://github.com/Arenukvern/mcp_flutter).
+Transport-agnostic agent intent platform for Dart/Flutter: define intent truth once in `AgentRegistry`, then project it into the strongest available surface: MCP/WebMCP, native action metadata where supported, assistant/shortcut fulfillment, and canonical deep-link fallback where native support is incomplete. Extracted from [mcp_flutter](https://github.com/Arenukvern/mcp_flutter).
 
-**Charter:** [docs/NORTH_STAR.mdx](docs/NORTH_STAR.mdx) · **Agent map:** [AGENTS.md](AGENTS.md)  
+**Charter:** [docs/NORTH_STAR.mdx](docs/NORTH_STAR.mdx) · **Agent map:** [AGENTS.md](AGENTS.md) · **Docs site:** [docs.page/Arenukvern/intentcall](https://docs.page/Arenukvern/intentcall)  
 **Why / how:** [docs/DESIGN_FAQ.mdx](docs/DESIGN_FAQ.mdx) · [docs/DX_FAQ.mdx](docs/DX_FAQ.mdx) · [Decisions](docs/decisions/) · [CONTRIBUTING.md](CONTRIBUTING.md)
 
 GitHub: [Arenukvern/intentcall](https://github.com/Arenukvern/intentcall)
@@ -35,7 +35,7 @@ GitHub: [Arenukvern/intentcall](https://github.com/Arenukvern/intentcall)
 | `intentcall_testing` | Contract / invoke test helpers |
 | `intentcall_gemma` / `intentcall_apple` / `intentcall_android` | Optional experimental surface adapters |
 
-Platform support is tiered during `0.1.x`: current emitters cover web/PWA, Apple App Intents artifacts, Android shortcuts/deep links, Windows protocol activation, and Linux `x-scheme-handler`; Android AppFunctions, Android App Actions capabilities, Windows App Actions / Agent Launchers, and AAIF ecosystem alignment are roadmap targets unless documented otherwise.
+Platform support is tiered during the `0.2.x` train: current code covers MCP, Dart-first WebMCP registration, Apple App Intents dispatch wrappers, Android shortcuts/deep links, Windows protocol activation, and Linux `x-scheme-handler`. Apple App Intents currently launch/wake the app and dispatch an invocation envelope for Dart execution; they do not claim app-extension-hosted Dart execution or native background business logic. Android AppFunctions, Android App Actions capabilities, Windows App Actions / Agent Launchers, and AAIF ecosystem alignment are roadmap targets unless documented otherwise.
 
 ## Agent Skills
 
@@ -57,7 +57,7 @@ just analyze
 just publish-dry-run   # pub.dev dry-run (all packages)
 ```
 
-Release maintainers additionally run `just publish-preflight-first` for the initial `0.1.0` publish, or `just publish-preflight` for later releases.
+Release maintainers use Release Please. Merging the release PR creates package tags; tag-triggered GitHub Actions publishes through pub.dev automated publishing.
 
 See [docs/DX_FAQ.mdx](docs/DX_FAQ.mdx) for detailed workflows.
 
@@ -75,4 +75,4 @@ See [CONTRIBUTING.md](CONTRIBUTING.md). All PRs must pass `just test && just ana
 
 ## Publishing
 
-See [PUBLISHING.md](PUBLISHING.md). Execute publish only from a clean release commit with pub.dev credentials: `just publish-execute`.
+See [PUBLISHING.md](PUBLISHING.md). The normal path is Release Please merge -> tag-triggered GitHub Actions publish; manual publish commands are recovery-only.

docs.json

@@ -0,0 +1,106 @@
+{
+  "$schema": "https://docs.page/schema.json",
+  "name": "IntentCall",
+  "description": "Register intents. Call them everywhere.",
+  "github": "https://github.com/Arenukvern/intentcall",
+  "theme": {
+    "defaultTheme": "system"
+  },
+  "header": {
+    "showName": true,
+    "showThemeToggle": true,
+    "showGitHubCard": true,
+    "links": [
+      {
+        "title": "GitHub",
+        "href": "https://github.com/Arenukvern/intentcall"
+      },
+      {
+        "title": "mcp_flutter",
+        "href": "https://github.com/Arenukvern/mcp_flutter"
+      }
+    ]
+  },
+  "content": {
+    "headerDepth": 3,
+    "automaticallyInferNextPrevious": true,
+    "showPageTitle": true
+  },
+  "sidebar": [
+    {
+      "group": "Start Here",
+      "pages": [
+        { "title": "Overview", "href": "/" },
+        { "title": "North Star", "href": "/NORTH_STAR" },
+        { "title": "Docs map", "href": "/start_here/docs_map" }
+      ]
+    },
+    {
+      "group": "FAQs",
+      "pages": [
+        { "title": "Design FAQ", "href": "/DESIGN_FAQ" },
+        { "title": "DX FAQ", "href": "/DX_FAQ" }
+      ]
+    },
+    {
+      "group": "Decisions",
+      "pages": [
+        { "title": "Index", "href": "/decisions/README" },
+        {
+          "title": "0010 — IntentCall product name",
+          "href": "/decisions/0010-adopt-intentcall-product-name"
+        },
+        {
+          "title": "0011 — Agent skills discoverability",
+          "href": "/decisions/0011-agent-skills-discoverability-for-intentcall"
+        },
+        {
+          "title": "0012 — Platform support tiers",
+          "href": "/decisions/0012-adopt-platform-support-tiers"
+        },
+        {
+          "title": "0013 — Plan hygiene",
+          "href": "/decisions/0013-delete-implemented-plans-after-durable-extraction"
+        },
+        {
+          "title": "0014 — Runtime sessions",
+          "href": "/decisions/0014-own-runtime-sessions-in-intentcall"
+        }
+      ]
+    },
+    {
+      "group": "Contributing",
+      "pages": [
+        {
+          "title": "Enable docs.page",
+          "href": "/contributing/enable_docs_page"
+        }
+      ]
+    },
+    {
+      "group": "Repo root (GitHub)",
+      "pages": [
+        {
+          "title": "README",
+          "href": "https://github.com/Arenukvern/intentcall/blob/main/README.md"
+        },
+        {
+          "title": "AGENTS.md",
+          "href": "https://github.com/Arenukvern/intentcall/blob/main/AGENTS.md"
+        },
+        {
+          "title": "CONTRIBUTING",
+          "href": "https://github.com/Arenukvern/intentcall/blob/main/CONTRIBUTING.md"
+        },
+        {
+          "title": "PRE_RELEASE",
+          "href": "https://github.com/Arenukvern/intentcall/blob/main/PRE_RELEASE.md"
+        },
+        {
+          "title": "PUBLISHING",
+          "href": "https://github.com/Arenukvern/intentcall/blob/main/PUBLISHING.md"
+        }
+      ]
+    }
+  ]
+}