Skip to content

Commit 3be269e

Browse files
willwashburnclaudegithub-actions[bot]agent-relay-code[bot]
authored
docs: make v8 the default docs version (#1032)
* docs: make v8 the default docs version Serve v8 docs at the bare /docs path and archive v7.1.1 under /docs/7.1.1, reachable via the version dropdown. - Flip currentDocsVersion to v8 and point v8DocsBasePath at /docs - Bare /docs/[slug] serves v8; legacy-only slugs redirect to the /docs/7.1.1 archive so v7 never renders at a canonical bare URL - Redirect /docs/8.0.0/* to the bare path to avoid duplicate content - Rewrite v8 MDX cross-links from /docs/8.0.0/* to /docs/* - Version dropdown lists v8.0.0 (latest) first, then v7.1.1 The sitemap continues to emit only the bare v8 slugs, so the v7.1.1 archive stays out of sitemap.xml. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * style: auto-format with Prettier * chore: apply pr-reviewer fixes for #1032 * style: auto-format with Prettier --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com> Co-authored-by: agent-relay-code[bot] <agent-relay-code[bot]@users.noreply.github.com>
1 parent 30d18e9 commit 3be269e

15 files changed

Lines changed: 198 additions & 237 deletions

File tree

‎.agentworkforce/trajectories/completed/2026-06/traj_4kjbodqi338z/summary.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Trajectory: Review and repair PR 1032
2+
3+
> **Status:** ✅ Completed
4+
> **Confidence:** 86%
5+
> **Started:** June 3, 2026 at 09:34 AM
6+
> **Completed:** June 3, 2026 at 09:38 AM
7+
8+
---
9+
10+
## Summary
11+
12+
Reviewed PR 1032 docs default-version changes. Removed stale Next bare-doc redirects that intercepted new v8 docs routes, taught docs version helpers to parse old /docs/8.0.0 URLs, and added focused unit tests for v8, legacy archive, and transitional paths. Web unit tests and web TypeScript pass; Next production build was attempted twice and killed by the host with exit 137 during optimized build.
13+
14+
**Approach:** Standard approach
15+
16+
---
17+
18+
## Key Decisions
19+
20+
### Removed stale bare docs redirect table
21+
22+
- **Chose:** Removed stale bare docs redirect table
23+
- **Reasoning:** Next redirects run before app routes and were redirecting new v8 bare docs pages such as /docs/cli-messaging to replacement pages, defeating the PR's v8 default routes and updated links.
24+
25+
---
26+
27+
## Chapters
28+
29+
### 1. Work
30+
31+
_Agent: default_
32+
33+
- Removed stale bare docs redirect table: Removed stale bare docs redirect table

‎.agentworkforce/trajectories/completed/2026-06/traj_4kjbodqi338z/trajectory.json‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
{
2+
"id": "traj_4kjbodqi338z",
3+
"version": 1,
4+
"task": {
5+
"title": "Review and repair PR 1032"
6+
},
7+
"status": "completed",
8+
"startedAt": "2026-06-03T09:34:08.197Z",
9+
"completedAt": "2026-06-03T09:38:44.581Z",
10+
"agents": [
11+
{
12+
"name": "default",
13+
"role": "lead",
14+
"joinedAt": "2026-06-03T09:36:12.926Z"
15+
}
16+
],
17+
"chapters": [
18+
{
19+
"id": "chap_p5kjoiqahyqj",
20+
"title": "Work",
21+
"agentName": "default",
22+
"startedAt": "2026-06-03T09:36:12.926Z",
23+
"endedAt": "2026-06-03T09:38:44.581Z",
24+
"events": [
25+
{
26+
"ts": 1780479372927,
27+
"type": "decision",
28+
"content": "Removed stale bare docs redirect table: Removed stale bare docs redirect table",
29+
"raw": {
30+
"question": "Removed stale bare docs redirect table",
31+
"chosen": "Removed stale bare docs redirect table",
32+
"alternatives": [],
33+
"reasoning": "Next redirects run before app routes and were redirecting new v8 bare docs pages such as /docs/cli-messaging to replacement pages, defeating the PR's v8 default routes and updated links."
34+
},
35+
"significance": "high"
36+
}
37+
]
38+
}
39+
],
40+
"retrospective": {
41+
"summary": "Reviewed PR 1032 docs default-version changes. Removed stale Next bare-doc redirects that intercepted new v8 docs routes, taught docs version helpers to parse old /docs/8.0.0 URLs, and added focused unit tests for v8, legacy archive, and transitional paths. Web unit tests and web TypeScript pass; Next production build was attempted twice and killed by the host with exit 137 during optimized build.",
42+
"approach": "Standard approach",
43+
"confidence": 0.86
44+
},
45+
"commits": [],
46+
"filesChanged": [],
47+
"projectId": "AgentWorkforce/relay",
48+
"tags": [],
49+
"_trace": {
50+
"startRef": "dcf8a069cd506fa8488b51260f71e99a507c25e8",
51+
"endRef": "dcf8a069cd506fa8488b51260f71e99a507c25e8"
52+
}
53+
}

‎web/app/docs/8.0.0/[slug]/page.tsx‎

Lines changed: 3 additions & 126 deletions
Original file line numberDiff line numberDiff line change
@@ -1,133 +1,10 @@
1-
import type { Metadata } from 'next';
2-
import type React from 'react';
3-
import { notFound } from 'next/navigation';
4-
import { evaluate } from '@mdx-js/mdx';
5-
import { Fragment } from 'react';
6-
import { jsx, jsxs } from 'react/jsx-runtime';
7-
import remarkGfm from 'remark-gfm';
8-
9-
import { BannerLink } from '../../../../components/docs/BannerLink';
10-
import { Card } from '../../../../components/docs/Card';
11-
import { CardGroup } from '../../../../components/docs/CardGroup';
12-
import { CodeGroup } from '../../../../components/docs/CodeGroup';
13-
import { DocsPageActions } from '../../../../components/docs/DocsPageActions';
14-
import { HighlightedPre } from '../../../../components/docs/HighlightedCode';
15-
import { Note } from '../../../../components/docs/Note';
16-
import { TableOfContents } from '../../../../components/docs/TableOfContents';
17-
import { Warning } from '../../../../components/docs/Warning';
18-
import styles from '../../../../components/docs/docs.module.css';
19-
import { getDoc } from '../../../../lib/docs';
20-
import { getDocMarkdownUrl } from '../../../../lib/docs-markdown';
21-
import { getAllDocSlugs } from '../../../../lib/docs-nav';
22-
import { absoluteUrl } from '../../../../lib/site';
23-
24-
function slugify(text: string): string {
25-
return text
26-
.toLowerCase()
27-
.replace(/`([^`]+)`/g, '$1')
28-
.replace(/[^a-z0-9]+/g, '-')
29-
.replace(/^-|-$/g, '');
30-
}
31-
32-
function HeadingWithId(level: 2 | 3) {
33-
return function Heading({ children, ...props }: React.HTMLAttributes<HTMLHeadingElement>) {
34-
const text = typeof children === 'string' ? children : String(children);
35-
const id = slugify(text);
36-
const Tag = `h${level}` as const;
37-
return (
38-
<Tag id={id} {...props}>
39-
{children}
40-
</Tag>
41-
);
42-
};
43-
}
44-
45-
const components = {
46-
BannerLink,
47-
Card,
48-
CardGroup,
49-
CodeGroup,
50-
Note,
51-
Warning,
52-
pre: HighlightedPre,
53-
h2: HeadingWithId(2),
54-
h3: HeadingWithId(3),
55-
};
1+
import { redirect } from 'next/navigation';
562

573
type PageProps = {
584
params: Promise<{ slug: string }>;
595
};
606

61-
export async function generateStaticParams() {
62-
return getAllDocSlugs().map((slug) => ({ slug }));
63-
}
64-
65-
export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
7+
export default async function V8DocsSlugRedirectPage({ params }: PageProps) {
668
const { slug } = await params;
67-
const doc = getDoc(slug, 'v8');
68-
69-
if (!doc) {
70-
return { title: 'Not Found' };
71-
}
72-
73-
return {
74-
title: `${doc.frontmatter.title} - Version 8.0.0`,
75-
description: doc.frontmatter.description,
76-
alternates: {
77-
canonical: absoluteUrl(`/docs/8.0.0/${slug}`),
78-
},
79-
openGraph: {
80-
title: `${doc.frontmatter.title} - Version 8.0.0`,
81-
description: doc.frontmatter.description,
82-
url: absoluteUrl(`/docs/8.0.0/${slug}`),
83-
type: 'article',
84-
},
85-
};
86-
}
87-
88-
export default async function V8DocsPage({ params }: PageProps) {
89-
const { slug } = await params;
90-
const doc = getDoc(slug, 'v8');
91-
92-
if (!doc) {
93-
notFound();
94-
}
95-
96-
const { default: MDXContent } = await evaluate(doc.content, {
97-
Fragment,
98-
jsx,
99-
jsxs,
100-
remarkPlugins: [remarkGfm],
101-
} as Parameters<typeof evaluate>[1]);
102-
103-
const pageUrl = absoluteUrl(`/docs/8.0.0/${slug}`);
104-
const markdownPath = `/docs/markdown/${slug}.md`;
105-
const markdownUrl = getDocMarkdownUrl(slug);
106-
107-
return (
108-
<div className={styles.articleWrapper}>
109-
<article className={styles.article}>
110-
<div className={styles.articleHeader}>
111-
<div className={styles.articleHeading}>
112-
<h1>{doc.frontmatter.title}</h1>
113-
</div>
114-
<DocsPageActions
115-
title={doc.frontmatter.title}
116-
pageUrl={pageUrl}
117-
markdownPath={markdownPath}
118-
markdownUrl={markdownUrl}
119-
/>
120-
</div>
121-
{doc.frontmatter.description && (
122-
<p className={styles.articleDescription}>{doc.frontmatter.description}</p>
123-
)}
124-
<div className={styles.articleBody}>
125-
<MDXContent components={components} />
126-
</div>
127-
</article>
128-
<aside className={styles.tocSidebar}>
129-
<TableOfContents items={doc.toc} />
130-
</aside>
131-
</div>
132-
);
9+
redirect(`/docs/${slug}`);
13310
}

‎web/app/docs/8.0.0/page.tsx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import { redirect } from 'next/navigation';
22

3-
export default function V8DocsIndexPage() {
4-
redirect('/docs/8.0.0/introduction');
3+
export default function V8DocsRedirectPage() {
4+
redirect('/docs/introduction');
55
}

‎web/app/docs/[slug]/page.tsx‎

Lines changed: 27 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
import type { Metadata } from 'next';
22
import type React from 'react';
3-
import { notFound } from 'next/navigation';
3+
import { notFound, redirect } from 'next/navigation';
44
import { evaluate } from '@mdx-js/mdx';
55
import { Fragment } from 'react';
66
import { jsx, jsxs } from 'react/jsx-runtime';
@@ -67,8 +67,19 @@ export async function generateStaticParams() {
6767

6868
export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
6969
const { slug } = await params;
70-
const version = getDefaultDocsVersionForSlug(slug);
71-
const doc = getDoc(slug, version, { linkBasePath: '/docs' });
70+
71+
// Legacy-only slugs live under /docs/7.1.1; point metadata there.
72+
if (getDefaultDocsVersionForSlug(slug) === 'v7.1.1') {
73+
const legacyDoc = getDoc(slug, 'v7.1.1');
74+
const canonical = absoluteUrl(`/docs/7.1.1/${slug}`);
75+
return {
76+
title: legacyDoc?.frontmatter.title ?? 'Not Found',
77+
description: legacyDoc?.frontmatter.description,
78+
alternates: { canonical },
79+
};
80+
}
81+
82+
const doc = getDoc(slug, 'v8');
7283

7384
if (!doc) {
7485
return { title: 'Not Found' };
@@ -91,8 +102,13 @@ export async function generateMetadata({ params }: PageProps): Promise<Metadata>
91102

92103
export default async function DocsPage({ params }: PageProps) {
93104
const { slug } = await params;
94-
const version = getDefaultDocsVersionForSlug(slug);
95-
const doc = getDoc(slug, version, { linkBasePath: '/docs' });
105+
106+
// Legacy-only slugs are served from the v7.1.1 archive, not the bare path.
107+
if (getDefaultDocsVersionForSlug(slug) === 'v7.1.1') {
108+
redirect(`/docs/7.1.1/${slug}`);
109+
}
110+
111+
const doc = getDoc(slug, 'v8');
96112

97113
if (!doc) {
98114
notFound();
@@ -108,7 +124,6 @@ export default async function DocsPage({ params }: PageProps) {
108124
const pageUrl = absoluteUrl(`/docs/${slug}`);
109125
const markdownPath = `/docs/markdown/${slug}.md`;
110126
const markdownUrl = getDocMarkdownUrl(slug);
111-
const showPageActions = version === 'v8';
112127

113128
return (
114129
<div className={styles.articleWrapper}>
@@ -117,14 +132,12 @@ export default async function DocsPage({ params }: PageProps) {
117132
<div className={styles.articleHeading}>
118133
<h1>{doc.frontmatter.title}</h1>
119134
</div>
120-
{showPageActions && (
121-
<DocsPageActions
122-
title={doc.frontmatter.title}
123-
pageUrl={pageUrl}
124-
markdownPath={markdownPath}
125-
markdownUrl={markdownUrl}
126-
/>
127-
)}
135+
<DocsPageActions
136+
title={doc.frontmatter.title}
137+
pageUrl={pageUrl}
138+
markdownPath={markdownPath}
139+
markdownUrl={markdownUrl}
140+
/>
128141
</div>
129142
{doc.frontmatter.description && (
130143
<p className={styles.articleDescription}>{doc.frontmatter.description}</p>

‎web/components/docs/DocsNav.tsx‎

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -92,12 +92,7 @@ export function DocsNav({ variant = 'sidebar' }: { variant?: 'sidebar' | 'mobile
9292
const isSidebar = variant === 'sidebar';
9393
const docsVersion = getDocsVersionForPath(pathname ?? '/docs');
9494
const navGroups = docsVersion === 'v7.1.1' ? legacyDocsNav : docsNav;
95-
const docsBasePath =
96-
docsVersion === 'v8'
97-
? v8DocsBasePath
98-
: (pathname ?? '').startsWith(legacyDocsBasePath)
99-
? legacyDocsBasePath
100-
: '/docs';
95+
const docsBasePath = docsVersion === 'v8' ? v8DocsBasePath : legacyDocsBasePath;
10196

10297
useEffect(() => {
10398
if (!isSidebar) return;

‎web/content/docs/cli-agent-management.mdx‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -107,16 +107,16 @@ A workspace identity can exist without a local process. A local process can be r
107107
## See Also
108108

109109
<CardGroup cols={2}>
110-
<Card title="Broker lifecycle" href="/docs/8.0.0/cli-broker-lifecycle">
110+
<Card title="Broker lifecycle" href="/docs/cli-broker-lifecycle">
111111
Start and stop the local runtime.
112112
</Card>
113-
<Card title="CLI messaging" href="/docs/8.0.0/cli-messaging">
113+
<Card title="CLI messaging" href="/docs/cli-messaging">
114114
Message agents after registering identities or spawning local sessions.
115115
</Card>
116-
<Card title="Workspaces" href="/docs/8.0.0/workspaces">
116+
<Card title="Workspaces" href="/docs/workspaces">
117117
How workspace keys define the coordination boundary.
118118
</Card>
119-
<Card title="Harnesses" href="/docs/8.0.0/harnesses">
119+
<Card title="Harnesses" href="/docs/harnesses">
120120
SDK/runtime concepts behind managed sessions.
121121
</Card>
122122
</CardGroup>

‎web/content/docs/cli-broker-lifecycle.mdx‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -91,16 +91,16 @@ agent-relay uninstall --keep-data
9191
## See Also
9292

9393
<CardGroup cols={2}>
94-
<Card title="Agent management" href="/docs/8.0.0/cli-agent-management">
94+
<Card title="Agent management" href="/docs/cli-agent-management">
9595
Spawn, attach, tail, release, and retarget local agents.
9696
</Card>
97-
<Card title="CLI messaging" href="/docs/8.0.0/cli-messaging">
97+
<Card title="CLI messaging" href="/docs/cli-messaging">
9898
Workspace message operations that do not require the local broker.
9999
</Card>
100-
<Card title="CLI reference" href="/docs/8.0.0/reference-cli">
100+
<Card title="CLI reference" href="/docs/reference-cli">
101101
Full command matrix.
102102
</Card>
103-
<Card title="MCP" href="/docs/8.0.0/agent-relay-mcp">
103+
<Card title="MCP" href="/docs/agent-relay-mcp">
104104
Give agents Relay tools through MCP.
105105
</Card>
106106
</CardGroup>

‎web/content/docs/cli-messaging.mdx‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -110,16 +110,16 @@ SDK-backed commands print JSON for successful reads and writes. Redirect or pipe
110110
## See Also
111111

112112
<CardGroup cols={2}>
113-
<Card title="Sending messages" href="/docs/8.0.0/sending-messages">
113+
<Card title="Sending messages" href="/docs/sending-messages">
114114
SDK equivalents for every message path.
115115
</Card>
116-
<Card title="Channels" href="/docs/8.0.0/channels">
116+
<Card title="Channels" href="/docs/channels">
117117
Channel concepts, membership, archive state, and read status.
118118
</Card>
119-
<Card title="DMs and group DMs" href="/docs/8.0.0/dms">
119+
<Card title="DMs and group DMs" href="/docs/dms">
120120
Direct and group direct messaging patterns.
121121
</Card>
122-
<Card title="Emoji reactions" href="/docs/8.0.0/emoji-reactions">
122+
<Card title="Emoji reactions" href="/docs/emoji-reactions">
123123
Reaction conventions and event examples.
124124
</Card>
125125
</CardGroup>

0 commit comments

Comments
 (0)