> ## Documentation Index
> Fetch the complete documentation index at: https://dialnexa.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# WEEKLY DOCS AUTOMATION

# Weekly Docs Automation

Use this runbook to configure a weekly Codex automation for DialNexa docs updates. The automation prepares a source delta report, updates the affected docs, asks for screenshots when needed, updates the changelog, validates the site, and opens a draft PR.

## What The Helper Scripts Do

* `scripts/prepare_weekly_docs_update.py` reads `DOCS_SOURCE_SNAPSHOT.md`, refreshes `master` refs for `dashboard-fe`, `dashboard-be`, and `speech-ai`, and writes a report under `.docs-update-reports/`.
* When `dashboard-be` has new commits, the prepare script also writes `.docs-update-reports/<run>/dashboard-be-v1-api-docs-audit.md`. This audit compares added `/v1` Nest routes against `api-reference/openapi.json` and flags removed `/v1` routes that are still present in OpenAPI or docs prose, so API changes cannot be missed silently.
* If the reported `dashboard-be` diff touches `src/modules/mcp/**`, run the export pipeline directly (see "MCP tool changes" below), then run `python3 scripts/validate_mcp_tool_docs.py`.
* `scripts/add_changelog_entry.py` inserts a dated entry into the matching monthly changelog page from a JSON file. It blocks em dash and en dash punctuation in visible changelog text.

The prepare script uses the correct local source repo names:

| Source repo    | Path                                           |
| -------------- | ---------------------------------------------- |
| `dashboard-fe` | `/Users/kamat/Documents/projects/dashboard-fe` |
| `dashboard-be` | `/Users/kamat/Documents/projects/dashboard-be` |
| `speech-ai`    | `/Users/kamat/Documents/projects/speech-ai`    |

It also accepts the older misspelled `dashbaord-fe` and `dashbaord-be` paths as fallback aliases.

## Manual Test Command

Run this from the docs repo root:

```bash theme={null}
python3 scripts/prepare_weekly_docs_update.py --output-dir .docs-update-reports/latest --force
```

Then open:

```text theme={null}
.docs-update-reports/latest/weekly-docs-update.md
```

## Codex Automation Setup

Create a new Codex automation with these settings:

* Workspace: `/Users/kamat/Documents/projects/api-docs`
* Schedule: weekly, at the day and time you want the docs review to start
* Model: use the strongest coding model available in your Codex automation settings
* Prompt: paste the prompt below

```text theme={null}
You are updating the DialNexa Mintlify docs in /Users/kamat/Documents/projects/api-docs.

Follow AGENTS.md exactly. Do not use em dash or en dash punctuation in docs prose. Keep changes scoped to source behavior changes. Review source diffs bidirectionally: new behavior may need docs added, and removed, renamed, hidden, deprecated, or unsupported behavior may need docs deleted or revised.

First run:

python3 scripts/prepare_weekly_docs_update.py --output-dir .docs-update-reports/latest --force

Read .docs-update-reports/latest/weekly-docs-update.md.

If dashboard-be changed, also read .docs-update-reports/latest/dashboard-be-v1-api-docs-audit.md. For every added v1 route that is not present in OpenAPI, decide whether it is public API, dashboard-only API, provider webhook, or internal API. Public API changes must update api-reference/openapi.json and matching MDX pages. For every removed v1 route that is still present in OpenAPI or still referenced in docs, delete the stale docs operation or reference. Intentionally excluded routes must be listed in the PR body with the reason.

If the dashboard-be diff touches src/modules/mcp/**, the MCP tool catalog may have changed (a tool added, removed, renamed, or its description or parameters edited). Re-sync the generated docs instead of hand-editing them. The prepare script only fetches dashboard-be's origin/master ref for diffing; it does not pull that commit into the sibling worktree, so the checkout on disk can be behind what the report just diffed. Before exporting, run the exporter from the exact origin/master commit in a clean or detached worktree. Do not switch or pull a dashboard-be worktree that has local changes. Then run `npm run mcp:export`, copy the resulting dashboard-be/scripts/output/mcp-tools.raw.json to mcp-tools/_generated/mcp-tools.raw.json in this repo, and run `python3 scripts/build-mcp-tools-from-export.py`. The builder creates one page per tool, group overviews, navigation entries, compatibility redirects, and the tracked manifest. Run `python3 scripts/validate_mcp_tool_docs.py` and review the generated diff. If endpoint, authentication, transport, or common response behavior changed, update the hand-authored MCP overview, quickstart, or error guide.

If all three source repos have 0 new commits, report that no docs update is needed and stop.

For each source repo with new commits:
1. Inspect the changed files listed in the report, including additions, deletions, renames, and behavior removals.
2. Read directly referenced helpers only when needed to understand user-facing behavior.
3. Decide which docs need additions, removals, or edits. Delete stale MDX prose, OpenAPI operations, docs.json navigation entries, screenshots, examples, and changelog links when the current codebase no longer supports them.
4. Update the affected MDX pages, docs.json, images, or api-reference/openapi.json.
5. For dashboard-be API changes, compare added and removed controllers, DTOs, guards, and routes.config entries against api-reference/openapi.json, API MDX pages, docs prose, and the API reference navigation.
6. If dashboard UI changes need screenshots, ask me for the exact screenshots needed and pause before creating a PR.

After I provide screenshots:
1. Add or replace the screenshot assets.
2. Update the affected docs with meaningful alt text.
3. Add a dated changelog entry to the matching monthly page under changelog/.
4. In the monthly changelog summary, use one table row per H3 update. Link each Update cell and each dated H3 update title to the exact destination section, not just the page top. Do not group multiple updates into one summary row.
5. If the changelog month page is new, add it under Changelog > Platform in docs.json.
6. Update DOCS_SOURCE_SNAPSHOT.md to the latest source commits from the report.
7. Run:

npx -y -p node@20 -p mint@latest mint validate
rg -n $'\u2014|\u2013' --glob '!mcp-tools/**' .
git diff --check
python3 -m json.tool api-reference/openapi.json >/dev/null
python3 -m json.tool docs.json >/dev/null
python3 scripts/validate_mcp_tool_docs.py

8. Fix any failures.
9. Commit the changes on a branch named codex/weekly-docs-update-YYYY-MM-DD.
10. Push the branch and open a draft PR for manual review.
11. In the PR body, include the source commit ranges, docs pages changed, screenshots requested or added, dashboard-be v1 API audit outcome, intentionally excluded routes, and validation results.
```

## Changelog Entry Helper

Create a JSON file like this when the weekly docs update is ready for changelog entry:

```json theme={null}
{
  "date": "2026-05-25",
  "updates": [
    {
      "title": "Batch call validation guidance",
      "body": "Updated recipient upload docs to explain grouped validation errors, failed row handling, and the expected correction flow."
    }
  ]
}
```

Insert it with:

```bash theme={null}
python3 scripts/add_changelog_entry.py --entry-file .docs-update-reports/latest/changelog-entry.json
```

The helper creates `changelog/<month-year>.mdx` when the month page does not exist. Add any new monthly page under the `Changelog > Platform` group in `docs.json`.

## Weekly Review Rules

* Do not update `DOCS_SOURCE_SNAPSHOT.md` until the docs have been edited and validated.
* Do not open a PR while waiting for screenshots.
* Keep changelog pages month-specific, with the same structure as `changelog/may-2026.mdx`: short intro, Documentation Index callout, `sidebarTitle`, `mode: "center"`, monthly H2, dated H2 sections, and concise H3 update titles. Set `tag: "LATEST"` only on the newest month page.
* In each monthly update summary, use one table row per H3 update. Link each Update cell and each dated H3 update title to the exact destination section for that change, not just the page top.
* If a source repo has local changes, the prepare script fetches `origin/master` but does not pull into that worktree. Use the reported `origin/master` commit for review.
* Treat `dashboard-be-v1-api-docs-audit.md` as a required checklist, not as a final decision. It flags route/OpenAPI gaps, stale documented removed routes, and stale removed-route prose references; Codex must still inspect the controller and DTO source before documenting, deleting, or excluding a route.
* Treat stale documentation as part of the weekly review. A removed or unsupported source feature should remove or revise docs even when no replacement feature was added.
* Keep `.docs-update-reports/` untracked. It is ignored by git.