ENG-2009 update llm docs authoring guidance for nextra docs tree

CONTRIBUTING.md

@@ -12,7 +12,7 @@ If you’re uncertain about the value of your proposed change, don’t hesitate
 
 Here’s how to contribute:
 
-1. [Fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) and [clone](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository) the repository.
+1. [Fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) or [clone](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository) the repository.
 2. [Create a new branch](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/managing-branches) for your updates.
 3. Implement your changes, making sure your code:
    - Is formatted with [Prettier](https://prettier.io)
@@ -50,11 +50,25 @@ Blog posts are located in `/apps/website/content/blog/`
 
 ### Plugin Documentation
 
-Detailed guidance for plugin docs lives next to the update-user-docs skill:
+Plugin docs live in the Nextra content tree:
 
-- **[navigation-mapping.md](./skills/update-user-docs/references/navigation-mapping.md)** — where files live, `docMap.ts` (shared pages), and `navigation.ts` (every new page)
-- **[doc-conventions.md](./skills/update-user-docs/references/doc-conventions.md)** — filenames, frontmatter, screenshots, and cross-links
-- **[scope-detection.md](./skills/update-user-docs/references/scope-detection.md)** — how changed file paths map to Obsidian vs Roam vs shared docs (useful when unsure where a doc belongs)
+- **Obsidian docs:** `apps/website/content/obsidian/...`
+- **Roam docs:** `apps/website/content/roam/...`
+
+Sidebar order comes from the nearest `_meta.ts` file in the content tree. If you add a page, add the Markdown or MDX file in the right section and update that section's `_meta.ts`.
+
+Flat legacy redirects, such as `/docs/obsidian/<slug>` to `/docs/obsidian/<section>/<slug>`, are maintained in `apps/website/docsRouteMap.ts`.
+
+Use existing Nextra Markdown, MDX, and `nextra/components` features for styling and layout before proposing anything custom. For example, use Nextra callouts, cards, steps, tabs, tables, and file trees when those fit the content.
+
+If the docs need a styling or presentation feature that Nextra does not currently provide, create a separate Linear ticket to add that Nextra functionality. Do not include theme, layout, route, component, or CSS changes in a content-only docs update.
+
+Preferred: Use the `$update-user-docs` skill to update plugin docs. Detailed guidance for plugin docs lives next to the `$update-user-docs` skill:
+
+- **[llm-authoring-guide.md](./skills/update-user-docs/references/llm-authoring-guide.md)** - a short guide non-devs can give to an LLM before asking it to write or update docs
+- **[navigation-mapping.md](./skills/update-user-docs/references/navigation-mapping.md)** - how `_meta.ts` controls sidebar registration and when `docsRouteMap.ts` needs a redirect
+- **[doc-conventions.md](./skills/update-user-docs/references/doc-conventions.md)** - filenames, frontmatter, screenshots, and cross-links
+- **[scope-detection.md](./skills/update-user-docs/references/scope-detection.md)** - how changed file paths map to Obsidian, Roam, both-platform, or docs-site updates
 
 ### Documentation Images
 
@@ -74,8 +88,8 @@ When referencing images in your documentation, use relative paths from the publi
 To preview your changes locally:
 
 1. **Environment setup**: Copy `/apps/website/.env.example` to `/apps/website/.env` and configure any necessary environment variables
-2. **Install dependencies**: Run `npm install` from the project root
-3. **Start development server**: Run `npm run dev` or `npx turbo dev` to start the website locally
+2. **Install dependencies**: Run `pnpm install` from the project root
+3. **Start development server**: Run `pnpm exec turbo dev -F website` or navigate to `apps/website` and run `pnpm dev` to start the website locally
 4. **View your changes**: Navigate to `http://localhost:3000` to see your documentation
 
 The website uses Next.js with the App Router, so changes to Markdown files should be reflected automatically during development.

skills/update-user-docs/SKILL.md

@@ -12,54 +12,80 @@ If `$ARGUMENTS` is provided, treat it as a GitHub PR number. Use `gh pr view $AR
 
 If no argument is provided, use the current branch's diff against main, commit messages, and any linked Linear ticket to determine what changed.
 
+## Guardrails
+
+- Edit live docs only under `apps/website/content/**`.
+- Put Obsidian docs under `apps/website/content/obsidian/**`.
+- Put Roam docs under `apps/website/content/roam/**`.
+- Do not edit legacy docs route shells or deleted legacy docs paths such as `apps/website/app/(docs)/docs/*/pages`, `docMap.ts`, `navigation.ts`, or `sharedPages`.
+- Do not update runtime code, app routes, or package interfaces unless the dev explicitly asks for that separately.
+- Use existing Nextra Markdown, MDX, and `nextra/components` features before proposing custom styling or layout.
+- Do not add or change theme, layout, route, component, or CSS code while adding documentation content. If existing Nextra features are not enough, flag the author to create a separate Linear ticket for new Nextra functionality.
+
 ## When to Run
 
 On demand. Two modes:
 
-- **Current branch** — Run while on a feature branch that's ready for PR or review.
-- **Merged PR** — Pass a PR number to generate docs for an already-merged PR that's missing documentation.
+- **Current branch** - Run while on a feature branch that's ready for PR or review.
+- **Merged PR** - Pass a PR number to generate docs for an already-merged PR that's missing documentation.
 
 ## Step 1: Gather Context
 
 ### If running for the current branch
 
 Collect information from three sources:
 
-1. **Changed files** — Run `git diff main...HEAD --name-only` to identify what changed. Use file paths to determine the affected platform (see [scope-detection.md](references/scope-detection.md) for mapping).
-2. **Commit messages** — Run `git log main...HEAD --oneline` for a summary of what was done.
-3. **Linear ticket** — If a Linear ticket is linked (branch name or PR description), pull the title, description, and acceptance criteria for additional context. Use Linear MCP if available. If it's not available, prompt the dev to install Linear MCP using these instructions: https://linear.app/docs/mcp
+1. **Changed files** - Run `git diff main...HEAD --name-only` to identify what changed. Use file paths to determine the affected platform (see [scope-detection.md](references/scope-detection.md) for mapping).
+2. **Commit messages** - Run `git log main...HEAD --oneline` for a summary of what was done.
+3. **Linear ticket** - If a Linear ticket is linked by branch name or PR description, pull the title, description, and acceptance criteria for additional context. Use the Linear connector if available. If it is not available, prompt the dev to install Linear MCP using these instructions: https://linear.app/docs/mcp
 
 ### If running for a merged PR
 
 Use the PR number to gather context via `gh`:
 
-1. **PR details** — Run `gh pr view <PR_NUMBER>` to get the title, description, and linked issues.
-2. **Changed files** — Run `gh pr diff <PR_NUMBER> --name-only` to identify what changed. Use file paths to determine the affected platform.
-3. **Linear ticket** — If a Linear ticket is referenced in the PR title, branch name, or description, pull additional context from it.
+1. **PR details** - Run `gh pr view <PR_NUMBER>` to get the title, description, and linked issues.
+2. **Changed files** - Run `gh pr diff <PR_NUMBER> --name-only` to identify what changed. Use file paths to determine the affected platform.
+3. **Linear ticket** - If a Linear ticket is referenced in the PR title, branch name, or description, pull additional context from it.
 
 ## Step 2: Determine If Docs Are Needed
 
-Apply the scope detection heuristic. See [scope-detection.md](references/scope-detection.md) for the full yes/no lists and file path → platform mapping.
+Apply the scope detection heuristic. See [scope-detection.md](references/scope-detection.md) for the full yes/no lists and file path to platform mapping.
 
 If no docs update is needed, inform the dev and stop.
 
 ## Step 3: New Page vs Update Existing
 
-1. Search existing documentation for content related to the change. See [doc-conventions.md](references/doc-conventions.md) for file locations.
-2. **Ask the dev:** "I found these existing pages that might be related: [list]. Should I update one of these, or create a new page?"
-3. Defaults:
-   - Completely new feature with no existing coverage → new page
-   - Extending or modifying an already-documented feature → update existing page
+1. Search existing docs only under `apps/website/content/**`.
+2. Prefer updating an existing page when the change extends or corrects an already-documented feature.
+3. Create a new page when the feature or workflow has no natural existing home.
+4. If multiple plausible homes exist, ask the dev which page or section should own the content.
+
+Defaults:
+
+- Completely new feature with no existing coverage -> new page.
+- Extending or modifying an already-documented feature -> update the existing page.
+- Change applies to both platforms -> update both platform docs unless the existing docs already share a conceptual page through both sidebars.
 
 ## Step 4: Write or Update the Doc
 
-Follow the formatting rules in [doc-conventions.md](references/doc-conventions.md) (frontmatter, filenames, screenshot placeholders, cross-link integrity, side observations).
+Follow the formatting rules in [doc-conventions.md](references/doc-conventions.md).
+
+For an **existing page**:
+
+1. Edit the Markdown or MDX file under the relevant `apps/website/content/**` path.
+2. Preserve existing frontmatter and local style.
+3. Verify any new links point to live docs routes or existing files.
+
+For a **new page**:
 
-If a **new page** is created, register it in navigation. See [navigation-mapping.md](references/navigation-mapping.md) for `docMap.ts` and `navigation.ts` patterns and examples.
+1. Choose the correct platform and section directory, such as `apps/website/content/obsidian/core-features/` or `apps/website/content/roam/guides/`.
+2. Add a kebab-case `.md` or `.mdx` file with frontmatter.
+3. Add the page slug to the nearest `_meta.ts` file so it appears in the sidebar. See [navigation-mapping.md](references/navigation-mapping.md).
+4. Update `apps/website/docsRouteMap.ts` only when a flat legacy redirect like `/docs/<platform>/<slug>` should continue to resolve to the new sectioned route.
 
 ## Step 5: Verification
 
 1. Present the draft changes to the dev for review.
-2. List any screenshot placeholders that need filling.
-3. Flag any broken cross-links or stale content observed.
-4. **Leave all changes as unstaged modifications** — do not commit. The dev reviews and commits themselves.
+2. List any screenshots that still need to be captured.
+3. Flag broken cross-links, missing route map redirects, or stale content observed while editing.
+4. Leave all changes as unstaged modifications. The dev reviews and commits themselves.

skills/update-user-docs/references/doc-conventions.md

@@ -1,49 +1,87 @@
 # Documentation Conventions
 
-## File Locations
+## File locations
 
-Platform-specific docs live in their respective directories:
+User-facing plugin docs live in the Nextra content tree:
 
-- **Obsidian:** `apps/website/app/(docs)/docs/obsidian/pages/`
-- **Roam:** `apps/website/app/(docs)/docs/roam/pages/`
-- **Shared (cross-platform):** `apps/website/app/(docs)/docs/sharedPages/`
+- Obsidian: `apps/website/content/obsidian/**`
+- Roam: `apps/website/content/roam/**`
+- Blog posts: `apps/website/content/blog/**`
+- Site-wide docs landing pages: `apps/website/content/**`
 
-Only place docs in `sharedPages/` if the content applies identically to both platforms and is explicitly specified as shared.
+Do not create plugin docs outside `apps/website/content/**`.
 
-## Filename Convention
+## Filename convention
 
-Use **kebab-case** for all doc filenames (e.g., `creating-discourse-nodes.md`).
+Use kebab-case for doc filenames, such as `creating-discourse-nodes.md`.
+Use `.md` for normal prose pages and `.mdx` only when the page needs components.
 
 ## Frontmatter
 
-Every doc file **must** include this frontmatter block:
+Every plugin doc file should include this frontmatter block unless nearby files in the same section use a different required shape:
 
 ```yaml
 ---
-title: "Page Title"
+title: "Page title"
 date: "YYYY-MM-DD"
 author: ""
 published: true
 ---
 ```
 
-## Screenshot Placeholders
+Use sentence case for page titles unless the title includes an official product name, plugin name, or UI label.
 
-For UI changes or new features with visual elements, insert a placeholder:
+## Nextra styling and formats
+
+Use existing Nextra Markdown, MDX, and `nextra/components` features before proposing custom styling.
+
+Good first choices include:
+
+- Standard Markdown headings, lists, links, tables, and code fences
+- Nextra `Callout` for warnings, tips, notes, and important context
+- Nextra `Cards` for small sets of high-level navigation options
+- Nextra `Steps` for ordered setup or workflow instructions
+- Nextra `Tabs` for compact platform or mode variants
+- Nextra `Table` and `FileTree` when structured data or file paths need clearer presentation
+
+Do not change docs structural code, theme files, route shells, app layouts, shared components, or CSS as part of adding content.
+If the content needs a styling or presentation feature that existing Nextra features cannot support, stop and flag the author to create a separate Linear ticket for adding that Nextra functionality.
+
+## Links
+
+- Prefer absolute docs routes for cross-page links, such as `/docs/obsidian/core-features/node-tags`.
+- Use relative links only when the target is in the same local section and the existing section already uses relative links.
+- Verify every new link points to an existing file or route.
+- Do not link to old flat routes when the current sectioned route is known.
+
+## Screenshots and media
+
+Place documentation images in `apps/website/public/docs/<platform>/`.
+
+Use public paths in Markdown:
 
 ```markdown
 <!-- TODO: Add screenshot of [describe the UI element or feature] -->
-
-![Screenshot placeholder](placeholder)
+<!-- ![Screenshot placeholder](/docs/roam/my-image.png) -->
 ```
 
-Always inform the dev that there are screenshot placeholders to fill in.
+For UI changes or visual features:
 
-## Cross-Link Integrity
+- Use a real screenshot when one is available.
+- If no screenshot is available, add an HTML TODO comment describing what should be captured.
+- Tell the dev exactly which screenshots still need to be captured.
+
+## Cross-link integrity
 
 - When adding or updating cross-links (e.g., `[text](./other-page)`), verify that the target page exists.
 - If a link target does not exist, flag it to the dev.
 
-## Side Observations
+## Cross-platform content
+
+If a change applies to both Obsidian and Roam, update both platform docs unless there is already a shared conceptual page surfaced from both sidebars.
+Keep platform-specific commands, settings names, and screenshots in the relevant platform section.
+
+## Side observations
 
-If while editing an existing doc you notice stale or incorrect content unrelated to the current change, flag it as a side observation to the dev. Do not silently fix unrelated content.
+If you notice stale or incorrect content unrelated to the current change, flag it as a side observation.
+Do not silently fix unrelated docs content unless the dev asks you to broaden the scope.

skills/update-user-docs/references/llm-authoring-guide.md

@@ -0,0 +1,78 @@
+# LLM Authoring Guide
+
+Use this guide when asking an LLM to write or update Discourse Graphs docs.
+
+## Copy/paste prompt
+
+```text
+Preferred: Use the $update-user-docs skill to update plugin docs.  If you cannot use the skill, follow these instructions:
+
+Write or update Discourse Graphs user docs in the live Nextra content tree only.
+
+Use these paths:
+- Obsidian docs: apps/website/content/obsidian/**
+- Roam docs: apps/website/content/roam/**
+- Sidebar order: nearest _meta.ts file
+- Flat legacy redirects: apps/website/docsRouteMap.ts
+
+Use existing Nextra Markdown, MDX, and nextra/components features first for styling and layout, such as Callout, Cards, Steps, Tabs, Table, and FileTree when appropriate.
+
+Do not edit route shells, theme/layout code, shared components, CSS, or legacy docs paths. Do not use app/(docs)/docs/*/pages, docMap.ts, navigation.ts, or sharedPages.
+
+If adding a page, choose the right platform section, create a kebab-case .md or .mdx file, update the nearest _meta.ts, and update docsRouteMap.ts only when a flat /docs/<platform>/<slug> redirect should exist.
+
+If existing Nextra features are not enough for the requested styling, do not implement new styling in the docs change. Ask for a separate Linear ticket to add the needed Nextra functionality.
+
+For screenshots, use real files in apps/website/public/docs/<platform>/ when available. If screenshots are missing, add an HTML TODO comment and list the needed screenshots in your summary. Do not add broken placeholder images.
+
+Before finishing, verify links, sidebar registration, route redirects, and stale legacy path references.
+```
+
+## Correct path examples
+
+- Existing Obsidian page: `apps/website/content/obsidian/core-features/creating-discourse-nodes.md`
+- New Obsidian page: `apps/website/content/obsidian/core-features/my-new-feature.md`
+- Existing Roam page: `apps/website/content/roam/guides/querying-discourse-graph.md`
+- Nested Roam section: `apps/website/content/roam/guides/exploring-discourse-graph/discourse-context.md`
+- Sidebar metadata: `apps/website/content/obsidian/core-features/_meta.ts`
+- Redirect map: `apps/website/docsRouteMap.ts`
+- Screenshots: `apps/website/public/docs/obsidian/my-screenshot.png`
+
+## Updating an existing page
+
+1. Search `apps/website/content/**` for the feature, setting, command, or workflow.
+2. Edit the closest existing platform page.
+3. Preserve frontmatter and the page's current tone.
+4. Verify every new link points to a live docs route or existing file.
+5. Mention any screenshot TODOs or unrelated stale content in the final summary.
+
+## Adding a new page
+
+1. Pick the platform: `obsidian` or `roam`.
+2. Pick the section that matches the user's workflow.
+3. Create a kebab-case `.md` or `.mdx` file.
+4. Add frontmatter with title, date, author, and published fields.
+5. Add the slug to the nearest `_meta.ts` file.
+6. Update `apps/website/docsRouteMap.ts` only if a flat legacy route should redirect to the sectioned route.
+
+## Screenshot handling
+
+Use screenshots only when the file exists or the dev provides it.
+If the screenshot is not available yet, add a comment like:
+
+```markdown
+<!-- TODO: Add screenshot of [describe the UI element or feature] -->
+<!-- ![Screenshot placeholder](/docs/obsidian/example-screenshot.png) -->
+```
+
+## Final review checklist
+
+- Docs edits are under `apps/website/content/**`.
+- New pages are registered in the nearest `_meta.ts`.
+- Needed flat redirects are in `apps/website/docsRouteMap.ts`.
+- Styling uses existing Nextra features and does not change structural code.
+- New links resolve to existing routes or files.
+- Screenshot TODOs are comments, not broken images.
+- No positive instructions point to legacy docs paths.
+
+Legacy warning: route shells and deleted legacy docs paths such as `app/(docs)/docs/*/pages`, `docMap.ts`, `navigation.ts`, and `sharedPages` are not docs authoring targets.