Update the docs

Every published page has one canonical Markdown source. Update that source and the website, search, and Datastat agent all receive the same reviewed answer.

Today, authors use GitHub's browser editor or edit Markdown locally. There is no separate visual CMS in this version.

Where the canonical source lives

datastat/docs-v2 is the canonical source for every page on this site. Edit the file directly under docs/<product>/; there is no upstream copy to keep in step and no import to wait for.

Use Edit this page in the footer to open the exact file. Its target is generated from the source_repository and source_path in that file's frontmatter, so it is always the file that produced the page you are reading.

Two exceptions are worth knowing:

• The internal/ui-labels-en-fr.md table in each product is generated by npm run docs:labels from that product's own source. Edit the product, not the table.
• FairReplay One has not been migrated yet and still lives on the old FairReplay site.

Edit in the browser

Use this route for a typo, unclear sentence, missing step, or other focused correction.

1. Open the page that needs work.
2. Select Edit this page in the footer.
3. Sign in to GitHub if asked.
4. Edit the Markdown. Keep the existing frontmatter unless its metadata also changed.
5. Create a branch from dev and open a pull request back to dev.
6. Explain what changed, why it is correct, and how a reviewer can verify it.

If you know that something is wrong but cannot supply the final wording, suggest a documentation correction instead. Include the page URL, the problem, and the expected answer. Never include credentials, personal data, customer data, or private access details.

Edit locally

Use a local checkout when the change spans several pages, changes navigation, or needs a full preview.

1. Open the datastat/docs-v2 repository and install its dependencies.

   npm install
   npm run dev
   

2. Edit the file under docs/<product>/ and preview it at the local URL printed by Next.js, normally http://localhost:3000/docs/datastat.

3. For a new page, or a change to its title, description, route, group, or order, also add or update its entry in localPages in scripts/import-legacy-docs.mjs, then regenerate the manifest. A page is published only once it is registered there.

   npm run docs:import
   

   The command reads nothing outside this repository, so it needs no other checkout and no network access.

4. Run the checks before requesting review.

   npm run docs:validate
   npm run lint
   npm run typecheck
   npm run build
   

5. Commit the source and any regenerated manifest together, then open a pull request to dev.

For a body-only change to an existing page, the manifest step is not required.

Add or replace an image

Do not copy a screenshot or logo directly into public/media. Public media is an approved allowlist.

1. Commit the image to this repository, next to the page that uses it.
2. Remove credentials, personal information, customer names, private URLs, and other sensitive details.
3. Add its path, SHA-256 hash, dimensions, privacy decision, and publication decision to scripts/reviewed-public-assets.json. An image published before the migration also records the repository and commit it was originally taken from.
4. Run the importer and validation.
5. Reference the approved public path from the page.

A Screenshot pending privacy review placeholder means a page refers to an image that has not passed those checks. Approve a sanitized replacement in the asset registry to replace the placeholder with the real image.

Review and publish

Automated checks prove that a page is structurally safe to integrate. They do not prove that its instructions are true. A Documentation Contributor may merge a focused pull request into dev after all required checks pass.

Explicit human approval is required for policies, security or access procedures, financial or HR rules, contractual material, production recovery procedures, and similar consequential instructions. Public pages must also pass security and personal-data review.

For a release, the maintainer opens a dev to main pull request, reviews the accumulated diff and rendered documentation, merges it while preserving the commit history, and creates a dated documentation release. The hosting system must then build the site from main. This repository does not currently define the hosting workflow, so the update is published only when the new build is live and the page shows the expected review date.

What the update changes

A successful publication updates one source and every way of using it:

• the canonical documentation page;
• sidebar navigation and tenant-scoped documentation search;
• /llms.txt and the agent-readable document when ai_index is enabled;
• the review date and provenance available to readers and the Datastat agent.

For the reader flow, continue to Find documentation. For answer behavior, read How the agent answers.