Add changeset release workflow and fix docs links

Author: optiflow

.changeset/config.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config/schema.json",
+  "access": "restricted",
+  "baseBranch": "main",
+  "changelog": [
+    "@changesets/changelog-github",
+    {
+      "repo": "optiflow/agent-memory-os"
+    }
+  ],
+  "commit": false,
+  "fixed": [],
+  "ignore": [
+    "@agent-memory-os/cli",
+    "@agent-memory-os/core",
+    "@agent-memory-os/docs",
+    "@agent-memory-os/docs-guard",
+    "@agent-memory-os/evals",
+    "@agent-memory-os/sqlite"
+  ],
+  "linked": [],
+  "privatePackages": {
+    "tag": false,
+    "version": true
+  },
+  "updateInternalDependencies": "patch"
+}

.changeset/release-pipeline.md

@@ -0,0 +1,5 @@
+---
+"agent-memory-os": minor
+---
+
+Add an automated Changesets and GitHub Actions pipeline for repository releases.

.github/workflows/release-metadata.yml

@@ -0,0 +1,37 @@
+name: Release Metadata
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  release-metadata:
+    name: Release metadata warning
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 11.5.1
+          run_install: false
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Check release metadata
+        run: pnpm release:check

.github/workflows/release.yml

@@ -0,0 +1,62 @@
+name: Release
+
+on:
+  workflow_run:
+    workflows:
+      - CI
+    types:
+      - completed
+    branches:
+      - main
+
+permissions:
+  contents: write
+  issues: read
+  pull-requests: write
+
+concurrency:
+  group: release-main
+  cancel-in-progress: false
+
+jobs:
+  release:
+    name: Changesets release
+    if: >-
+      ${{
+        github.event.workflow_run.conclusion == 'success' &&
+        github.event.workflow_run.event == 'push'
+      }}
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.workflow_run.head_sha }}
+
+      - name: Set up pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 11.5.1
+          run_install: false
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Create version PR or GitHub Release
+        uses: changesets/action@v1
+        with:
+          commit: Version Agent Memory OS
+          createGithubReleases: false
+          publish: pnpm release:github
+          title: Version Agent Memory OS
+          version: pnpm changeset:version
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

AGENTS.md

@@ -102,6 +102,9 @@
 ## Commands
 
 - Install: `pnpm install`
+- Create a changeset: `pnpm changeset`
+- Apply pending changesets to versions and changelogs:
+  `pnpm changeset:version`
 - Lint: `pnpm lint`
 - Package lint: `pnpm lint:packages`
 - Repo-wide lint: `pnpm lint:repo`
@@ -119,6 +122,29 @@
 - Full local gate: `pnpm run ci`
 - Hermes adapter compile and unit tests: `pnpm adapter:check`
 - Install git hooks: `pnpm hooks:install`
+- Release metadata warning check: `pnpm release:check`
+- Create GitHub release from `CHANGELOG.md`: `pnpm release:github`
+
+## Release Workflow
+
+- Releases are repository-level GitHub Releases only. Do not add npm publishing
+  or `NPM_TOKEN` requirements unless explicitly requested.
+- Significant changes or improvements require a changeset targeting
+  `agent-memory-os`. Use `pnpm changeset`, then choose the smallest valid semver
+  bump: patch for fixes and docs/tooling polish, minor for new capabilities, and
+  major only for breaking public behavior.
+- Non-release PRs should include `[no release]` in the PR title or body. Use it
+  for chore-only changes, CI experiments, or edits that should not become release
+  notes.
+- The release metadata workflow is warning-only. Treat warnings as review input,
+  not a failing gate.
+- The release workflow runs after the `CI` workflow succeeds on `main`.
+  `changesets/action` opens or updates the `Version Agent Memory OS` PR while
+  changesets are pending. After that version PR merges, the workflow runs
+  `pnpm release:github` and creates `Agent Memory OS vX.Y.Z` from the matching
+  root `CHANGELOG.md` section.
+- Do not manually edit generated version PR contents unless fixing the release
+  metadata itself. Prefer adding or amending changesets in feature PRs.
 
 ## Verification
 

apps/docs/src/content/docs/index.md

@@ -11,14 +11,14 @@ architecture, contracts, verification, and roadmap boundaries live in detail.
 
 | If you need to... | Read |
 | --- | --- |
-| Run the repo from a fresh checkout | [Getting Started](./start/getting-started.md) |
-| Confirm local runtime expectations | [Environment](./start/environment.md) |
-| Understand the system shape | [Architecture](./architecture/architecture.md) |
-| Inspect stored objects and projections | [Data Model](./architecture/data-model.md) |
-| Call the JSON CLI bridge | [CLI Reference](./reference/cli-reference.md) |
-| Verify quality gates and evals | [Evaluation](./reference/evaluation.md) |
-| Install or inspect the Hermes boundary | [Hermes Install Notes](./integrations/hermes-install.md) |
-| Check phase boundaries | [Roadmap](./roadmap/v1-v2-roadmap.md) |
+| Run the repo from a fresh checkout | [Getting Started](./start/getting-started/) |
+| Confirm local runtime expectations | [Environment](./start/environment/) |
+| Understand the system shape | [Architecture](./architecture/architecture/) |
+| Inspect stored objects and projections | [Data Model](./architecture/data-model/) |
+| Call the JSON CLI bridge | [CLI Reference](./reference/cli-reference/) |
+| Verify quality gates and evals | [Evaluation](./reference/evaluation/) |
+| Install or inspect the Hermes boundary | [Hermes Install Notes](./integrations/hermes-install/) |
+| Check phase boundaries | [Roadmap](./roadmap/v1-v2-roadmap/) |
 
 ## Current Shape
 

apps/docs/src/content/docs/reference/evaluation.md

@@ -46,6 +46,7 @@ pnpm build
 pnpm adapter:check
 pnpm docs:check
 pnpm docs:build
+pnpm release:check
 ```
 
 ## Documentation Freshness
@@ -59,7 +60,7 @@ pnpm docs:check
 The guard fails when code, adapter, tooling, workflow, or policy changes land
 without the matching documentation surface in the same diff. It checks changed
 paths, validates `.devin/wiki.json`, and rejects stale canonical references to
-deleted root `docs/*.md` files.
+deleted root `docs/*.md` files or Starlight links to source-file URLs.
 
 Expected behavior:
 
@@ -71,13 +72,40 @@ Expected behavior:
   adapter or install docs;
 - tooling and docs-guard policy changes require `AGENTS.md`, environment docs,
   or this evaluation page;
+- Starlight content links must use published route paths, not `.md` source-file
+  URLs or related typo variants;
 - `.devin/wiki.json` must stay valid, use unique page titles, and reference
   existing priority files.
 
 The guard does not update DeepWiki. DeepWiki is a generated external index: keep
 `.devin/wiki.json` current, then audit the refreshed wiki after merge before
 claiming the public DeepWiki page is current.
 
+## Release Automation
+
+Releases are Changesets-gated repository releases. Feature, fix, docs, adapter,
+or tooling improvements that should appear in release notes need a changeset for
+the root `agent-memory-os` package:
+
+```bash
+pnpm changeset
+```
+
+Use patch for fixes and docs/tooling polish, minor for new capabilities, and
+major only for breaking public behavior. PRs that intentionally should not
+produce a release can use `[no release]` in the PR title or body.
+
+The `Release Metadata` workflow runs `pnpm release:check` on pull requests. It
+emits warnings for release-relevant changes without a changeset, but it does not
+fail CI.
+
+After the `CI` workflow succeeds on `main`, the `Release` workflow runs
+`changesets/action`. Pending changesets create or update the `Version Agent
+Memory OS` PR. When that version PR merges, `pnpm release:github` reads the root
+`CHANGELOG.md`, uses the current root `package.json` version, and creates a
+single GitHub Release titled `Agent Memory OS vX.Y.Z`. The repo does not publish
+packages to npm.
+
 ## CLI Smoke Test
 
 ```bash

apps/docs/src/content/docs/start/getting-started.md

@@ -32,7 +32,7 @@ The full gate runs documentation freshness checks, linting, typechecking,
 tests, builds, adapter-boundary checks, deterministic evals, and report-only
 benchmarks.
 
-For narrower checks, see [Evaluation](../reference/evaluation.md).
+For narrower checks, see [Evaluation](../../reference/evaluation/).
 
 ## CLI Smoke Test
 
@@ -71,7 +71,7 @@ skills             Bundled Hermes setup runbook
 
 ## Next Reads
 
-- [CLI Reference](../reference/cli-reference.md) for command contracts.
-- [Architecture](../architecture/architecture.md) for memory planes and routing.
-- [Hermes Install Notes](../integrations/hermes-install.md) for adapter setup.
-- [Evaluation](../reference/evaluation.md) for local acceptance gates.
+- [CLI Reference](../../reference/cli-reference/) for command contracts.
+- [Architecture](../../architecture/architecture/) for memory planes and routing.
+- [Hermes Install Notes](../../integrations/hermes-install/) for adapter setup.
+- [Evaluation](../../reference/evaluation/) for local acceptance gates.

package.json

@@ -8,9 +8,11 @@
     "adapter:check": "python3 -m py_compile __init__.py adapters/hermes/plugins/memory/meta_memory/__init__.py adapters/hermes/plugins/memory/meta_memory/test/test_provider.py && python3 -m unittest discover adapters/hermes/plugins/memory/meta_memory/test",
     "bench": "turbo run bench --filter @agent-memory-os/evals",
     "bench:ci": "turbo run bench:ci --filter @agent-memory-os/evals",
-    "build": "turbo run build",
+    "build": "turbo run build --filter='!agent-memory-os'",
+    "changeset": "changeset",
+    "changeset:version": "changeset version",
     "ci": "pnpm docs:check && pnpm lint && pnpm typecheck && pnpm test && pnpm build && pnpm adapter:check && pnpm eval && pnpm bench:ci",
-    "clean": "turbo run clean",
+    "clean": "turbo run clean --filter='!agent-memory-os'",
     "docs:check": "pnpm --filter @agent-memory-os/docs-guard build && node packages/docs-guard/dist/index.js",
     "docs:build": "pnpm --filter @agent-memory-os/docs build",
     "docs:dev": "pnpm --filter @agent-memory-os/docs dev",
@@ -19,14 +21,18 @@
     "format": "biome format --write .",
     "hooks:install": "lefthook install",
     "lint": "pnpm lint:packages && pnpm lint:repo",
-    "lint:packages": "turbo run lint",
+    "lint:packages": "turbo run lint --filter='!agent-memory-os'",
     "lint:repo": "biome check .",
     "prepare": "lefthook install",
-    "test": "turbo run test",
-    "typecheck": "turbo run typecheck"
+    "release:check": "node scripts/check-release-metadata.mjs",
+    "release:github": "node scripts/create-github-release.mjs",
+    "test": "turbo run test --filter='!agent-memory-os'",
+    "typecheck": "turbo run typecheck --filter='!agent-memory-os'"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.16",
+    "@changesets/changelog-github": "^0.7.0",
+    "@changesets/cli": "^2.31.0",
     "@types/node": "24.12.4",
     "lefthook": "2.1.9",
     "turbo": "2.9.16",

packages/docs-guard/src/docsGuard.ts

@@ -38,6 +38,7 @@ export function runDocsGuard(options: DocsGuardOptions): DocsGuardResult {
     ...validateChangedFileRules(changedFiles),
     ...validateWikiJson(options.repoRoot),
     ...validateRootDocsReferences(options.repoRoot),
+    ...validateStarlightSourceLinks(options.repoRoot),
   ];
 
   return {
@@ -304,6 +305,35 @@ function validateRootDocsReferences(repoRoot: string): string[] {
   return errors;
 }
 
+function validateStarlightSourceLinks(repoRoot: string): string[] {
+  const docsPath = join(repoRoot, STARLIGHT_DOCS_PREFIX);
+  if (!existsSync(docsPath)) {
+    return [];
+  }
+
+  const errors: string[] = [];
+  const markdownLinkPattern = /(?<!!)\[[^\]\n]+\]\(([^)\s]+)(?:\s+["'][^"']*["'])?\)/g;
+
+  for (const filePath of walkFiles(docsPath, repoRoot).filter((file) => file.endsWith(".md"))) {
+    const content = readFileSync(join(repoRoot, filePath), "utf8");
+    for (const match of content.matchAll(markdownLinkPattern)) {
+      const rawTarget = match[1]?.trim().replace(/^<|>$/g, "");
+      if (!rawTarget || isExternalLink(rawTarget) || rawTarget.startsWith("#")) {
+        continue;
+      }
+
+      const targetPath = rawTarget.split("#")[0]?.split("?")[0] ?? "";
+      if (/\.(md|mdb)$/i.test(targetPath)) {
+        errors.push(
+          `Starlight source link "${rawTarget}" in ${filePath} points at a source file. Use the published route path instead.`,
+        );
+      }
+    }
+  }
+
+  return errors;
+}
+
 function docsReferenceScanFiles(repoRoot: string): string[] {
   const files: string[] = [];
 
@@ -388,6 +418,10 @@ function isToolingOrPolicyChange(file: string): boolean {
   );
 }
 
+function isExternalLink(linkTarget: string): boolean {
+  return /^[a-z][a-z0-9+.-]*:/i.test(linkTarget) || linkTarget.startsWith("//");
+}
+
 function isObject(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }