Repository navigation
feat(site): improve agent readiness - #20
Conversation
There was a problem hiding this comment.
🟡 Changes recommended
Several lastModified values are set to a future date (2026-08-24) relative to the PR timestamp, which will surface as incorrect “updated” UI and sitemap metadata.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
This PR enhances the kmsg documentation site’s “agent readiness” by expanding the localized route set, publishing Markdown alternates alongside prerendered HTML (including legacy aliases), adding trust/developer resources pages, and embedding homepage JSON-LD for SoftwareApplication + Organization metadata.
Changes:
- Expanded the localized canonical route table from 32 → 44 pages and added new “Developers / About / Contact” content across ko/en/jp/cn.
- Updated the static build pipeline to emit
index.mdMarkdown alternates for canonical pages and serve legacy aliases as full prerendered pages (no meta refresh). - Added homepage JSON-LD structured data and tightened site build tests to assert substantive prerendered HTML, sitemap integrity, robots/llms discovery, and Markdown artifacts.
File summaries
| File | Description |
|---|---|
| site/test/routes.test.ts | Updates route-count expectations and adds locale target coverage for new pages. |
| site/test/metadata.test.ts | Adds test coverage for homepage JSON-LD structured data graph. |
| site/test/markdown-content.test.mjs | Updates expected synced Markdown entry count for expanded docs set. |
| site/test/build.test.mjs | Expands build artifact assertions for Markdown alternates, legacy aliases, SEO/meta contracts, and structured data. |
| site/scripts/sync-markdown-content.mjs | Syncs additional Markdown-backed pages and merges trust content into document content generation. |
| site/scripts/build-static.mjs | Writes Markdown alternates, copies prerender output for legacy aliases, enriches 404 recovery content, and updates discovery files. |
| site/content/ko/developers.md | Adds localized developer resources page (Korean). |
| site/content/ko/contact.md | Adds localized contact/support page (Korean). |
| site/content/ko/about.md | Adds localized about/trust page (Korean). |
| site/content/jp/developers.md | Adds localized developer resources page (Japanese). |
| site/content/jp/contact.md | Adds localized contact/support page (Japanese). |
| site/content/jp/about.md | Adds localized about/trust page (Japanese). |
| site/content/en/developers.md | Adds localized developer resources page (English). |
| site/content/en/contact.md | Adds localized contact/support page (English). |
| site/content/en/about.md | Adds localized about/trust page (English). |
| site/content/cn/developers.md | Adds localized developer resources page (Chinese). |
| site/content/cn/contact.md | Adds localized contact/support page (Chinese). |
| site/content/cn/about.md | Adds localized about/trust page (Chinese). |
| site/app/root.tsx | Adds Markdown alternate <link> and injects homepage JSON-LD; updates discovery link relationship. |
| site/app/lib/metadata.ts | Introduces homepageStructuredData() JSON-LD graph and keeps per-page metadata behavior intact. |
| site/app/content/trust-content.json | Adds new trust/developer page copy with explicit lastModified metadata. |
| site/app/content/routes.ts | Extends PAGE_KEYS and slug mappings for new pages. |
| site/app/content/pages.ts | Merges trust content with legacy content for page copy lookup. |
| site/app/content/legacy-content.json | Updates privacy copy to reflect expanded data-boundary and reporting guidance. |
| site/app/content/document-content.json | Adds generated document entries for new pages and updates some last-modified timestamps. |
| site/app/components/site-footer.tsx | Adds footer navigation links for new trust/developer resources pages. |
| site/app/components/mobile-navigation.tsx | Adds mobile nav entry for the Developers page. |
Review details
- Files reviewed: 26/27 changed files
- Comments generated: 0
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
💡 Codex Reviewkmsg/Sources/kmsg/Commands/WatchCommand.swift Lines 336 to 342 in f8284ba  Keep same-minute messages in the watch stream
When a watch starts at 12:34:30, KakaoTalk's minute-resolution label gives a new 12:34 message a logical timestamp of 12:34:00, so this comparison rejects every message received during the rest of that minute; messages without a parseable timestamp are also rejected unconditionally. As a result, kmsg/Sources/kmsg/Commands/WatchCommand.swift Lines 428 to 430 in f8284ba Emit the first event after an empty baseline
When stabilization completes before any post-start message arrives, kmsg/Sources/kmsg/KakaoTalk/ChatWindowResolver.swift Lines 135 to 137 in f8284ba Resolve chat IDs before matching windows by display name
When two chats share the same display name and either one already has an open window, kmsg/Sources/kmsg/Auth/KakaoTalkAuthenticator.swift Lines 117 to 119 in f8284ba Refuse interactive credential prompts without a TTY
When an automatic command runs logged out with no saved credentials, this path prompts without checking kmsg/Sources/kmsg/KakaoTalk/TranscriptReader.swift Lines 1114 to 1118 in f8284ba Preserve repeated messages in transcript results
For two legitimate messages with the same author, displayed minute, and body—for example, sending kmsg/.github/workflows/pages.yml Lines 34 to 35 in f8284ba Fetch history before deriving document timestamps
The Pages workflow uses checkout's one-commit default, but both site generation scripts derive unpinned document dates with kmsg/.github/workflows/pages.yml Lines 11 to 14 in f8284ba  Trigger Pages when VERSION changes
The documented release bump creates a commit that changes only AGENTS.md reference: AGENTS.md:L66-L66 ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
|
@codex review Please review current head |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 7ff2576c20
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| const target = `${baseUrl}${page.publicPath}` | ||
| const legacyPath = `ko/${pageSlugs[page.pageKey]}index.html` | ||
| await write(legacyPath, redirectDocument(target, "ko")) | ||
| await copyOutput(`${page.publicPath}index.html`, legacyPath) |
There was a problem hiding this comment.
When a browser opens a copied Korean alias such as /kmsg/ko/usage/, this serves the canonical page together with its client bundle, but after hydration routeFromPath() cannot resolve /ko/usage/ because Korean canonical routes omit the ko segment, so PageRoute throws its 404 response and replaces the initially valid page. The copied openclaw aliases have the same problem because the router only recognizes mcp; either retain redirects or explicitly normalize these compatibility routes before hydration.
Useful? React with 👍 / 👎.
|
|
||
| ## MCP server | ||
|
|
||
| The [MCP guide](../mcp/) documents `kmsg mcp-server`, a stdio server exposing `kmsg_read`, `kmsg_send`, and `kmsg_send_image`. Clients launch the installed binary and exchange JSON-RPC through standard input and output. kmsg currently has no first-party Streamable HTTP MCP endpoint or live `/.well-known/mcp` handshake; a static GitHub Pages response cannot represent a POST-based MCP session. |
There was a problem hiding this comment.
On every localized developer page, this ../mcp/ target is passed through resolveMarkdownTarget(), whose markdownPageKey() recognizes openclaw but not mcp. Consequently the generated HTML links to https://github.com/channprj/kmsg/blob/main/site/content/mcp/, a nonexistent repository path, instead of the localized /kmsg/<locale>/mcp/ page. Recognize mcp as the openclaw document key or use the source filename in these links.
Useful? React with 👍 / 👎.
| const markdown = await readFile(resolve(repoDir, page.source), "utf8") | ||
| return markdown.endsWith("\n") ? markdown : `${markdown}\n` |
There was a problem hiding this comment.
When an agent follows one of the new index.md links from llms.txt, the source document is copied verbatim, so repository-relative links no longer point to the published layout. For example, /kmsg/index.md contains links such as USAGE.md, ARCHITECTURE.md, and LICENSE; these resolve under /kmsg/ to files that are not emitted, while the available pages are /kmsg/usage/index.md and /kmsg/architecture/index.md. Transform relative links for the static Markdown location, as the HTML content pipeline already does, or link them back to repository sources.
Useful? React with 👍 / 👎.
|
@codex review Please re-review current head |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 711b1fa106
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| ## Events and webhooks | ||
|
|
||
| Run `kmsg watch --json` as a local process for newline-delimited message events. kmsg does not operate a hosted webhook delivery or callback registration service. If a workflow needs webhooks, an operator-owned supervisor must validate local events, apply approval policy, and deliver them to an endpoint the operator controls. |
There was a problem hiding this comment.
Consumers following this developer page will treat each line from kmsg watch --json as a complete JSON event, but WatchCommand.emitJSON() uses JSONEncoder with .prettyPrinted and then writes two newlines, so a single event spans many lines. A line-oriented supervisor will therefore attempt to parse fragments such as { and fail; either emit compact one-object-per-line JSON or document the output as a whitespace-separated stream of pretty-printed JSON values.
Useful? React with 👍 / 👎.
Summary
Verification
npm test: Vitest 53 passed, Node 18 passed, typecheck/build passed711b1fa: full suite passed711b1fa: successko/usage,en/openclaw,ko/openclaw: correct H1/title, no ErrorBoundarygit diff --checkReview remediation
711b1fareported no suggestionsExplicit hosting constraints
GitHub Pages cannot provide request-time
Accept: text/markdownnegotiation,Vary: Accept, or a Streamable HTTP MCP POST endpoint. This PR publishes standards-based Markdown alternates and documents the native stdio MCP server without claiming unsupported HTTP behavior.