Railly · Oct 1, 2026 · Oct 1, 2026
diff --git a/apps/docs/content/docs/agents.mdx b/apps/docs/content/docs/agents.mdx
@@ -1,6 +1,7 @@
 ---
-title: Agents and skills
-description: Install the issue-graph skill and use it to trace issues, check PR status, and review backlogs.
+title: Agent skill for issue and PR context
+navTitle: Agents and skills
+description: Install the issue-graph agent skill so coding agents can trace issues, check PR status, review backlogs, and return exact dashboard links.
 lastModified: 2026-09-27
 ---
 

diff --git a/apps/docs/content/docs/backlog.mdx b/apps/docs/content/docs/backlog.mdx
@@ -1,6 +1,7 @@
 ---
-title: Reconcile and plan
-description: Find backlog items to verify and get an ordered queue of reviews and investigations.
+title: Reconcile a backlog and plan reviews
+navTitle: Reconcile and plan
+description: Find backlog items to verify, review suggested actions, check coverage, compare competing PRs, and get an ordered queue of reviews.
 lastModified: 2026-09-27
 ---
 

diff --git a/apps/docs/content/docs/dashboard.mdx b/apps/docs/content/docs/dashboard.mdx
@@ -1,6 +1,7 @@
 ---
-title: Dashboard and saved queries
-description: Filter captured work, open an exact dashboard view, replay decisions, and configure scoring defaults.
+title: Dashboard, saved queries, and filters
+navTitle: Dashboard and saved queries
+description: Capture a repository, filter and rank its open work, open an exact dashboard view, replay past decisions, and keep scoring defaults.
 lastModified: 2026-09-27
 ---
 

diff --git a/apps/docs/content/docs/get-started.mdx b/apps/docs/content/docs/get-started.mdx
@@ -1,6 +1,7 @@
 ---
-title: Get started
-description: Install issue-graph, sign in with GitHub CLI, and trace your first issue.
+title: Install the CLI and trace your first issue
+navTitle: Get started
+description: Install issue-graph from npm, sign in with GitHub CLI, trace your first issue, and save the result as JSON or an HTML explorer.
 lastModified: 2026-09-27
 ---
 

diff --git a/apps/docs/content/docs/graph.mdx b/apps/docs/content/docs/graph.mdx
@@ -1,6 +1,7 @@
 ---
-title: Graph
-description: Trace linked issues and pull requests, compare saved results, and export an HTML explorer.
+title: Trace linked issues and pull requests
+navTitle: Graph
+description: Trace the issues and pull requests linked to one item, control crawl depth and budget, compare snapshots, and export JSON or HTML.
 lastModified: 2026-09-27
 ---
 

diff --git a/apps/docs/content/docs/index.mdx b/apps/docs/content/docs/index.mdx
@@ -1,6 +1,7 @@
 ---
-title: Overview
-description: Find related issues, check pull request status, and plan backlog reviews from your terminal.
+title: Map related issues and pull requests
+navTitle: Overview
+description: Trace related issues and pull requests from your terminal, check review status, find existing fixes, and choose what to review next.
 lastModified: 2026-09-27
 ---
 

diff --git a/apps/docs/content/docs/library.mdx b/apps/docs/content/docs/library.mdx
@@ -1,6 +1,7 @@
 ---
-title: Library
-description: Use issue-graph in your application with a GitHub CLI or HTTP transport.
+title: Use issue-graph as a library
+navTitle: Library
+description: Use issue-graph in your application to crawl issue graphs, collect PR status, and query dashboard models over HTTP or GitHub CLI.
 lastModified: 2026-09-27
 ---
 

diff --git a/apps/docs/content/docs/reference.mdx b/apps/docs/content/docs/reference.mdx
@@ -1,6 +1,7 @@
 ---
-title: Command reference
-description: Look up CLI commands, flags, output formats, storage options, and exit codes.
+title: CLI command reference and exit codes
+navTitle: Command reference
+description: Look up issue-graph commands, flags, output formats, crawl controls, storage options, and exit codes, plus help and JSON schema output.
 lastModified: 2026-09-27
 ---
 

diff --git a/apps/docs/content/docs/security.mdx b/apps/docs/content/docs/security.mdx
@@ -1,6 +1,7 @@
 ---
-title: Permissions and privacy
-description: Configure GitHub access and understand which commands save files or send data to an external agent.
+title: Permissions, local files, and privacy
+navTitle: Permissions and privacy
+description: Configure GitHub access, see which commands save local files or send data to an external agent, and share captured results carefully.
 lastModified: 2026-09-27
 ---
 

diff --git a/apps/docs/content/docs/status.mdx b/apps/docs/content/docs/status.mdx
@@ -1,6 +1,7 @@
 ---
-title: Status and history
-description: Count pull requests by author and repository, check review states, and compare saved reports.
+title: Pull request status and review history
+navTitle: Status and history
+description: Check open pull requests by repository and author, read review-state counts and draft or conflict flags, pick an output format, and compare captures.
 lastModified: 2026-09-27
 ---
 

diff --git a/apps/docs/src/app/docs/[[...slug]]/page.tsx b/apps/docs/src/app/docs/[[...slug]]/page.tsx
@@ -6,7 +6,7 @@ import { docsPath, isSafePathSegments, markdownPath } from "@/lib/docs-paths";
 import { config } from "@/lib/geistdocs/config";
 import { geistdocsSource } from "@/lib/geistdocs/source";
 import { pageMetadata } from "@/lib/page-metadata";
-import { siteDescription } from "@/lib/site";
+import { canonicalUrl, siteDescription, siteName } from "@/lib/site";
 
 type PageProps = { params: Promise<{ slug?: string[] }> };
 
@@ -34,7 +34,46 @@ const docsPage = createDocsPage({
 
 export default async function Page({ params }: PageProps) {
   const validated = await getPage(params);
-  return <docsPage.Page params={Promise.resolve(validated.params)} />;
+  const { page } = validated;
+  const url = canonicalUrl(docsPath(page.slugs));
+  // The Geistdocs frontmatter schema keeps navTitle, but PageData does not type it.
+  const { navTitle } = page.data as { navTitle?: string };
+  const structuredData = {
+    "@context": "https://schema.org",
+    "@graph": [
+      {
+        "@type": "TechArticle",
+        headline: page.data.title,
+        description: page.data.description ?? siteDescription,
+        url,
+        isPartOf: { "@type": "WebSite", name: siteName, url: canonicalUrl("/") },
+      },
+      {
+        "@type": "BreadcrumbList",
+        itemListElement: [
+          { "@type": "ListItem", position: 1, name: "Docs", item: canonicalUrl("/docs") },
+          ...(page.slugs.length
+            ? [
+                {
+                  "@type": "ListItem",
+                  position: 2,
+                  name: navTitle ?? page.data.title,
+                  item: url,
+                },
+              ]
+            : []),
+        ],
+      },
+    ],
+  };
+  return (
+    <>
+      <script type="application/ld+json">
+        {JSON.stringify(structuredData).replace(/</g, "\\u003c")}
+      </script>
+      <docsPage.Page params={Promise.resolve(validated.params)} />
+    </>
+  );
 }
 
 export async function generateMetadata({ params }: PageProps) {

diff --git a/apps/docs/src/app/page.tsx b/apps/docs/src/app/page.tsx
@@ -5,18 +5,39 @@ import { InstallSelector } from "@/components/install-selector";
 import { renderTerminalCommand } from "@/components/terminal-output";
 import { landingDescription, landingTitle, workflows } from "@/lib/landing-content";
 import { pageMetadata } from "@/lib/page-metadata";
-import { plannedInstallCommand, siteDescription, siteName, siteUrl } from "@/lib/site";
+import {
+  plannedInstallCommand,
+  repositoryUrl,
+  siteDescription,
+  siteName,
+  siteUrl,
+} from "@/lib/site";
 import "@/components/landing.css";
 
 export const metadata = pageMetadata("/", landingTitle, siteDescription);
 
 export default function Home() {
   const structuredData = {
     "@context": "https://schema.org",
-    "@type": "WebSite",
-    name: siteName,
-    url: siteUrl,
-    description: siteDescription,
+    "@graph": [
+      {
+        "@type": "WebSite",
+        name: siteName,
+        url: siteUrl,
+        description: siteDescription,
+      },
+      {
+        "@type": "SoftwareApplication",
+        name: siteName,
+        url: siteUrl,
+        description: siteDescription,
+        applicationCategory: "DeveloperApplication",
+        operatingSystem: "Node.js 20+",
+        license: "https://www.apache.org/licenses/LICENSE-2.0",
+        sameAs: [repositoryUrl, "https://www.npmjs.com/package/issue-graph"],
+        offers: { "@type": "Offer", price: "0", priceCurrency: "USD" },
+      },
+    ],
   };
 
   return (

diff --git a/apps/docs/tests/content.test.ts b/apps/docs/tests/content.test.ts
@@ -50,7 +50,7 @@ describe("documentation content contract", () => {
 
   test("names the docs entry Overview", async () => {
     const intro = await read("content/docs/index.mdx");
-    expect(intro).toMatch(/^title: Overview$/m);
+    expect(intro).toMatch(/^navTitle: Overview$/m);
   });
 
   test("documents published npm-first installation and preserves access boundaries", async () => {