DELETED Markdown linting POC

.claude/.markdownlint.yaml

@@ -1,6 +1,7 @@
-# Claude Agent and command definitions are prompts, not templates or user documentation.
+# Files in this directory include Claude Agent and command definitions
+# which are prompts parsed by Claude Agents
 
-# They must inherit the standard common prompt rules
-# These linting rules cascades to both .claude/agents/ and .claude/commands/.
+# They inherit the basic linting rules as well as the common prompt rules
+# These linting rules cascade to all folders in the .claude folder.
 
 extends: ../.markdownlint-prompts.yaml

.claude/agents/documentation-pr-reviewer.md

@@ -1,28 +1,66 @@
 ---
 name: documentation-pr-reviewer
-description: Use this agent when reviewing pull requests that contain documentation changes, changelog updates, or release notes. This includes PRs modifying README files, API documentation, user guides, CHANGELOG.md, migration guides, or any markdown documentation files. Examples:\n\n<example>\nContext: User has just created a PR updating the API documentation and wants feedback before merging.\nuser: "I've updated the API docs for the new authentication endpoints. Can you review the PR?"\nassistant: "I'll use the Task tool to launch the doc-pr-reviewer agent to thoroughly review your documentation PR."\n<commentary>The user is requesting a review of documentation changes, which is exactly when the doc-pr-reviewer agent should be used.</commentary>\n</example>\n\n<example>\nContext: User mentions they've made changes to the changelog.\nuser: "Just pushed changelog updates for v2.0 release"\nassistant: "Let me use the doc-pr-reviewer agent to review your changelog updates for completeness and clarity."\n<commentary>Changelog updates should be reviewed by this agent to ensure they follow best practices and are clear for users.</commentary>\n</example>\n\n<example>\nContext: Agent proactively notices a PR with documentation changes.\nassistant: "I notice you've opened a PR with documentation changes. Let me use the doc-pr-reviewer agent to review it for clarity, accuracy, and completeness."\n<commentary>The agent should proactively offer to review documentation PRs when it detects them in the conversation context.</commentary>\n</example>
-tools: Bash, Skill, SlashCommand, Glob, Grep, Read, WebFetch, TodoWrite, WebSearch, BashOutput
+description: |-
+  Use this agent when reviewing pull requests that contain documentation changes or changelog updates. This includes PRs modifying README files, user guides, CHANGELOG.md, migration guides, or any markdown documentation files. Examples:
+
+  <example>
+  Context: User has just created a PR updating the user documentation for a new feature and wants feedback before merging.
+  user: "I've updated the docs for the new UI feature. Can you review the PR?"
+  assistant: "I'll use the Task tool to launch the documentation-pr-reviewer agent to thoroughly review your documentation PR."
+  <commentary>The user is requesting a review of documentation changes, which is exactly when the documentation-pr-reviewer agent should be used.</commentary>
+  </example>
+
+  <example>
+  Context: User mentions they've made changes to the changelog.
+  user: "Just pushed changelog updates for today"
+  assistant: "Let me use the documentation-pr-reviewer agent to review your changelog updates for completeness and clarity."
+  <commentary>Changelog updates should be reviewed by this agent to ensure they follow best practices and are clear for users.</commentary>
+  </example>
+
+  <example>
+  Context: Agent proactively notices a PR with documentation changes.
+  assistant: "I notice you've opened a PR with documentation changes. Let me use the documentation-pr-reviewer agent to review it for accuracy and completeness."
+  <commentary>The agent should proactively offer to review the PRs when it detects them in the conversation context.</commentary>
+  </example>
+tools: Read, Glob, Grep, WebFetch(domain:github.com,domain:raw.githubusercontent.com),Bash(uv run prek run *),Bash(uv run zensical build --clean *)
 model: sonnet
 ---
 
 # Documentation PR Reviewer Agent
 
-You are a technical documentation reviewer focused on clarity, accuracy, and user experience for documentation and changelog PRs.
+You are a technical documentation reviewer focused on clarity, accuracy, and user experience for end user documentation and changelog PRs.
 
 ## Review Checklist
 
-### Documentation
+### User Documentation
+
+- Page-type contract: Read `.claude/checklists/page-type-contract.md` — verify each changed page is in the right folder with required elements present.
+- Quality gate: Read `.claude/checklists/doc-self-review.md` and check each item against the changed page(s).
 - Clarity: Flag jargon, ambiguity, or complex explanations
-- Accuracy: Verify technical correctness, check code examples work
+- Accuracy: Verify UI/feature claims against the OCS source at https://github.com/dimagi/open-chat-studio/; if you cannot fetch it, say so explicitly in your final report.
+- Use the CONTEXT.md file (https://raw.githubusercontent.com/dimagi/open-chat-studio/main/CONTEXT.md) to verify terminology, concepts, and features, and to resolve any terminology ambiguities in the codebase and UI.
 - Structure: Ensure logical flow, proper headings, intuitive navigation
 - Consistency: Check terminology, formatting, and alignment with existing docs
-- Links: Validate all internal/external references
+- Links: Validate all internal references
 
 ### Changelog
-- Categorization: Verify correct grouping (Added, Changed, Fixed, etc.) and semantic versioning
+
+- Categorization: Verify entries are date-grouped and use the correct category prefix (`**NEW**`, `**CHANGE**`, `**BUG**`, `**MIGRATION**`)
 - User Impact: Ensure entries explain what changed and why it matters
 - Breaking Changes: Must be highlighted with migration guidance
-- Format: Follow Keep a Changelog standards
+- Format: Follow existing Changelog standards
+
+### README
+
+- Target Audience: Ensure README is clear for engineers maintaining the repo.
+- Accuracy: Verify technical correctness of the information provided against this repo's codebase
+- Content: Ensure content covers topics like the "why" of usage, configuration, assumptions, and constraints.
+
+### Build & Lint
+
+- Run `uv run prek run markdownlint-cli2 --all-files` and report any failures.
+- Run `uv run zensical build --clean` and report any failures.
+- If the PR touches `.github/workflows/*.yml`, run `uv run prek run actionlint --files <paths>` and report any failures.
 
 ## Output Format
 
@@ -32,17 +70,11 @@ You are a technical documentation reviewer focused on clarity, accuracy, and use
 
 **Suggestions**: Optional improvements with reasoning
 
-**Code Examples**: Specific feedback on correctness and completeness
+**Code Examples**: Specific feedback on usefulness and completeness
 
 **Minor Issues**: Typos, formatting, style nitpicks
 
 ## Decisions
-- Request Changes: Accuracy issues, missing critical info, broken examples, clarity problems
+- Request Changes: Accuracy issues, missing critical info, clarity problems
 - Approve: Clear, accurate, complete, follows best practices
 - Comment: Minor suggestions that don't block merging
-
-## Standards
-- Assume varying technical backgrounds
-- Prioritize user needs; favor concrete examples
-- Explain "why" not just "what" and "how"
-- Remove fluff

.claude/agents/zensical-technical-writer.md

@@ -37,7 +37,7 @@ You are an expert technical documentation writer for Open Chat Studio — a plat
 ### 1. Read the code for context before writing
 
 - Locate the relevant source code for the topic in https://github.com/dimagi/open-chat-studio/
-- Use the CONTEXT.md file (https://github.com/dimagi/open-chat-studio/blob/main/CONTEXT.md) to understand terminology, concepts, and features, and to resolve any terminology ambiguities in the codebase and UI.
+- Use the CONTEXT.md file (https://raw.githubusercontent.com/dimagi/open-chat-studio/main/CONTEXT.md) to understand terminology, concepts, and features, and to resolve any terminology ambiguities in the codebase and UI.
 
 If you cannot fetch the source (no web access in this environment), say so explicitly in your final report and write from the PR title, body, and diff supplied in the prompt. Do not invent behaviour you have not seen — flag anything you inferred rather than confirmed.
 
@@ -50,26 +50,17 @@ Based on the topic, determine the target user type(s) and write accordingly. The
 
 ### 3. Choose the correct page type
 
-Determine the page type using the table below (and whether the content needs multiple linked pages).
-
-| Page type | Folder | Audience | Must include | Must not include | Example |
-|---|---|---|---|---|---|
-| Concepts | `concepts/` | End users, advanced users, developers | High-level "why"/"what" explanation, simple language | Jargon, API instructions, code examples — link to Tech Hub/How-To instead | `concepts/sessions.md` |
-| How-To Guide | `how-to/` | End users, advanced users, developers | Prerequisites, numbered steps (imperative verbs), prose example use cases, expected outcomes, brief common-issues list | Code snippets, in-depth troubleshooting/diagnostics — link to Tech Hub instead | `how-to/adjust_llm_node_model_parameters.md` |
-| Tech Hub | `tech-hub/` | Advanced users, developers | Code examples with expected output, API references, in-depth troubleshooting, architecture/implementation detail | Repeating Concepts/How-To content — link to it instead | `tech-hub/template_and_email_nodes.md` |
-| Tutorial | `tutorials/` | End users (first-time) | Numbered steps (imperative verbs), simple real-world application | Advanced features, complex config, code, API references, common pitfalls — write a How-To Guide instead | `tutorials/configure_llm_node.md` |
-| Chat Widget | `chat_widget/` | Developers | Prerequisites, code examples, API references, troubleshooting | General OCS/end-user content | `chat_widget/reference.md` |
-
-Diagrams and flowcharts (e.g. mermaid) are useful on any page type to illustrate concepts or steps — use sparingly on Tutorials, which should stay simple for first-time users.
+Determine the page type using `.claude/checklists/page-type-contract.md`
+(and whether the content needs multiple linked pages).
 
 ### 4. Write or update the page or pages
 
-- Use the correct page type template and include its required elements (see the table above).
+- Use the correct page type template and include its required elements (see `.claude/checklists/page-type-contract.md`).
 - Follow the editorial conventions below — voice, terminology, structure, formatting. If a convention is undefined for a situation, match the closest existing pattern in the current docs rather than inventing a new style.
 
 ### 5. Review and edit the draft
 
-- Self-check against the Self-Review checklist below
+- Self-check against the checklist in `.claude/checklists/doc-self-review.md`
 
 ## Editorial conventions
 
@@ -81,11 +72,12 @@ Diagrams and flowcharts (e.g. mermaid) are useful on any page type to illustrate
 - Numbered steps style for How-To Guides and Tutorials: use a flat numbered list under a single H2 for guides of up to ~6 steps; use `## Step N: Title` headings for longer ones. Don't mix the two styles on the same page.
 - Group related features together in the site content navigation and updating mkdocs.yml navigation if needed
 
-### Follow Zensical best practices
+### Follow markdown and Zensical best practices
 
 - Create internal links using relative paths.
+- Use semantic linefeeds (one sentence per line) rather than breaking lines for fixed width.
 - Use admonitions for notes, warnings, and tips (`!!! note`, `!!! warning`).
-- Where code examples are permitted for the page type (see table above), use code fences with language specification for syntax highlighting.
+- Where code examples are permitted for the page type (see `.claude/checklists/page-type-contract.md`), use code fences with language specification for syntax highlighting.
 
 ### Quality standards
 
@@ -97,12 +89,5 @@ Diagrams and flowcharts (e.g. mermaid) are useful on any page type to illustrate
 
 ## Self-Review checklist
 
-Before finalising documentation:
-- [ ] Does the page open with a purpose statement (see Structure for discoverability)?
-- [ ] Are all technical terms defined or linked?
-- [ ] Are any of the pages updated now too long (over 100 lines of markdown source)? Should any sections be shortened or split into separate pages?
-- [ ] Is there information on a long page that should be separated out into another page of a different page type?
-- [ ] Is there any duplication of content with other pages? If so, should it be merged or linked instead?
-- [ ] Are there enough internal links to related content?.
-- [ ] Is formatting and page structure consistent with existing docs?
-- [ ] Have I used admonitions only for genuine notes, warnings, or tips (not as a formatting crutch)?
+See `.claude/checklists/doc-self-review.md` (shared with the
+`documentation-pr-reviewer` agent — edit it there, not here, if the bar changes).

.claude/checklists/doc-self-review.md

@@ -0,0 +1,12 @@
+# Documentation Self-Review Checklist
+
+- [ ] Page is no more than ~100 lines of markdown source, or split into multiple pages if longer.
+- [ ] Content that belongs to a different page type (see `page-type-contract.md`) is separated into its own page rather than mixed in.
+- [ ] No duplication with other existing pages — merged or linked instead.
+- [ ] Page opens with a purpose statement: what it covers and why it matters.
+- [ ] All OCS terminology and technical terms are defined on first use or linked to a Concept page.
+- [ ] Enough internal links to and from related content.
+- [ ] Semantic linefeeds (one sentence per line) are used in newly written or edited paragraphs.
+- [ ] Sentences are under 25 words.
+- [ ] Semantic linefeeds are used (one sentence per line) and not breaking lines by fixed column width.
+- [ ] Admonitions (`!!! note`, `!!! warning`) are used only for genuine notes, warnings, or tips — not as a formatting crutch.

.claude/checklists/page-type-contract.md

@@ -0,0 +1,11 @@
+# Page-Type Contract
+
+| Folder | Page type | Audience | Must include | Must not include | Example |
+|---|---|---|---|---|---|
+| `concepts/` | Concepts | End users, advanced users, developers | High-level "why"/"what" explanation, simple language | Jargon, API instructions, code examples — link to Tech Hub/How-To instead | `concepts/sessions.md` |
+| `how-to/` | How-To Guide | End users, advanced users, developers | Prerequisites, numbered steps (imperative verbs), prose example use cases, expected outcomes, brief common-issues list | Code snippets, in-depth troubleshooting/diagnostics — link to Tech Hub instead | `how-to/adjust_llm_node_model_parameters.md` |
+| `tech-hub/` | Tech Hub | Advanced users, developers | Code examples with expected output, API references, in-depth troubleshooting, architecture/implementation detail | Repeating Concepts/How-To content — link to it instead | `tech-hub/template_and_email_nodes.md` |
+| `tutorials/` | Tutorial | End users (first-time) | Numbered steps (imperative verbs), simple real-world application | Advanced features, complex config, code, API references, common pitfalls — write a How-To Guide instead | `tutorials/configure_llm_node.md` |
+| `chat_widget/` | Chat Widget | Developers | Prerequisites, code examples, API references, troubleshooting | General OCS end-user content | `chat_widget/reference.md` |
+
+Diagrams and flowcharts (e.g. mermaid) are useful on any page type to illustrate concepts or steps.

.claude/commands/review-pr.md

@@ -1,5 +1,5 @@
 ---
-allowed-tools: Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*)
+allowed-tools: Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),WebFetch(domain:github.com,domain:raw.githubusercontent.com),Bash(uv run prek run *),Bash(uv run zensical build --clean *)
 description: Review a pull request
 ---
 

.github/workflows/ci.yml

@@ -1,3 +1,16 @@
+# CI Workflow
+#
+# Builds the Zensical docs site and publishes it to GitHub Pages.
+#
+# Triggered on: push to main
+# Requirements: none — deploy-pages authenticates via the job's own Pages/OIDC
+# permissions, no external secrets needed
+#
+# Notes:
+# - No concurrency group, so back-to-back pushes to main can deploy in parallel
+#   with no ordering guarantee — a slower, older run can finish after a newer one
+#   and leave stale content live.
+
 name: ci
 on:
   push:
@@ -14,12 +27,15 @@ jobs:
       url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
     permissions:
-      contents: read
-      pages: write
-      id-token: write
+      contents: read   # needed for checkout
+      pages: write     # needed by actions/deploy-pages
+      id-token: write  # needed by actions/deploy-pages (OIDC)
+
     steps:
       - uses: actions/configure-pages@v6
       - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
 
       - name: Install uv
         uses: astral-sh/setup-uv@v7

.github/workflows/claude-review.yml

@@ -47,4 +47,14 @@ jobs:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
           prompt: "/review-pr REPO: ${{ github.repository }} PR_NUMBER: ${{ github.event.pull_request.number }}"
           claude_args: |
-            --allowedTools "Task,Read,Grep,Glob,mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*)"
+            --allowedTools "Task,
+            Read,
+            Grep,
+            Glob,
+            mcp__github_inline_comment__create_inline_comment,
+            Bash(gh pr comment:*),
+            Bash(gh pr diff:*),
+            Bash(gh pr view:*),
+            WebFetch(domain:github.com,domain:raw.githubusercontent.com),
+            Bash(uv run prek run *),
+            Bash(uv run zensical build --clean *)"

.github/workflows/update-api-docs.yml

@@ -1,3 +1,18 @@
+# Update API Documentation Workflow
+#
+# Regenerates docs/api/ from the OCS OpenAPI schema — fetches the schema files
+# from the OCS repo, runs them through src/ocs_docs/openapi_to_docs.py, and opens
+# a PR with the result if anything changed. docs/api/ is generated; don't hand-edit.
+#
+# Triggered on: repository_dispatch (`ocs_api_update`) from the OCS repo; a daily
+# schedule (02:00 UTC) as a backstop; or workflow_dispatch (manual)
+# Requirements: OCS_AGENT_APP_ID (var) / OCS_AGENT_PRIVATE_KEY (secret) for the
+# ocs-agent GitHub App token used to open the PR
+#
+# Notes:
+# - Labelled `automated`, same as update-changelog.yml's PRs — keeps these PRs
+#   out of the AI review in claude-review.yml (see README-claude-workflows.md).
+
 name: Update API Documentation
 
 on:
@@ -15,14 +30,14 @@ jobs:
     runs-on: ubuntu-latest
 
     permissions:
-      contents: write
-      pull-requests: write
+      contents: read  # needed for checkout and the cross-repo `gh api` read; PR creation uses the ocs-agent app token
 
     steps:
       - name: Checkout repository
         uses: actions/checkout@v7
         with:
           fetch-depth: 0
+          persist-credentials: false
 
       - name: Install uv
         uses: astral-sh/setup-uv@v7
@@ -77,7 +92,8 @@ jobs:
         with:
           app-id: ${{ vars.OCS_AGENT_APP_ID }}
           private-key: ${{ secrets.OCS_AGENT_PRIVATE_KEY }}
-
+          permission-contents: write
+          permission-pull-requests: write
       - name: Create Pull Request
         if: steps.check_changes.outputs.has_changes == 'true'
         uses: peter-evans/create-pull-request@v8