Enhancements to documentation agentic workflow

- ensure conventions of versioned docs are followed
- ensure flows and concepts are using facing documentation and do not include technical stuff
- specify which model to use

Co-authored-by: Copilot <copilot@github.com>

Author: rithviknishad

.claude/skills/care-flow-doc/SKILL.md

@@ -8,7 +8,7 @@ description: >-
   "document how to do X", "the steps are out of date", or "this flow is missing".
   Covers the quality bar (create-patient), the page structure, sourcing steps from
   care_fe rather than guessing, the manual flow sidebar, link/MDX conventions,
-  3.0≡3.1 versioning, and build validation.
+  the manual flow sidebar, link/MDX conventions, versioning, and build validation.
 ---
 
 # Building Care flow docs
@@ -17,13 +17,17 @@ A **flow** answers _"How do I…?"_ — it walks a user through one task in the
 start to finish. It is neither a concept (what a thing _is_) nor a reference (what
 fields it _has_). A reader arrives at a flow with a job to do.
 
-Flows live at `versioned_docs/version-3.0/flows/<domain>/<slug>.mdx`, mirrored to
-`version-3.1`. One task per page.
+Flows live at `flows/<domain>/<slug>.mdx` under the versioned docs. Follow the shared
+conventions for which version to author in and how to mirror. One task per page.
+
+A flow is **strictly user-facing**. Clinicians and operators read it. Never put code,
+file paths, class names, API endpoints, payloads, database columns or permission slugs
+in a flow.
 
 ## The quality bar
 
-The gold standard is `versioned_docs/version-3.0/flows/clinical/create-patient.mdx`.
-**Read it every time.** Study how a good flow:
+The gold standard is `flows/clinical/create-patient.mdx`. **Read it every time.** Study
+how a good flow:
 
 - Opens with one sentence naming the task and its end state ("the minimum path from
   search to a saved record ready for an encounter").
@@ -32,7 +36,10 @@ The gold standard is `versioned_docs/version-3.0/flows/clinical/create-patient.m
 - Separates **what you need before you start** from **the steps themselves**.
 - Numbers steps as `### 1. <imperative>` and keeps each one to a single decision.
 - Uses a table when a step has a set of fields, not a wall of prose.
-- Ends with what the user can do next, and the API equivalent for implementers.
+- Ends with what the user can do next.
+
+It also carries an `## API equivalent` section. Do not copy that part: flows are now
+strictly user-facing, and the technical surface belongs in the reference doc.
 
 ## Naming
 
@@ -53,8 +60,9 @@ Use the same `<domain>` folders as concepts and references.
   Mention a keyboard shortcut only if `care_fe/src/config/keyboardShortcuts.json`
   actually defines one for that action.
 - `## After <the task>` — what the user can do next, as a `| Next step | When |` table.
-- `## API equivalent` — the request an implementer would send, in an ```` ```http ````
-  fence. Take the path and payload from the code, not from memory.
+
+Do **not** add an API or payload section. Flows are user-facing; the technical surface
+belongs in the matching reference doc, which the flow can link to.
 
 ## Sources
 
@@ -63,10 +71,9 @@ Use the same `<domain>` folders as concepts and references.
    navigation labels. Take every user-visible string from `public/locale/en.json`;
    enum display labels use keys shaped `PREFIX__value` (`encounter_status__in_progress`
    → "In Progress"). Never print a raw codebase value in a flow.
-2. **`care`** — for the permission the task needs and the API equivalent. Trace the
-   viewset's `authorize_*` hook to the permission slug the way the concept skill
-   describes; state it in plain words ("a role with **patient create** permission"),
-   not as a slug.
+2. **`care`** — for the permission the task needs. Trace the viewset's `authorize_*`
+   hook to the permission slug the way the concept skill describes, then state it in
+   plain words ("a role with **patient create** permission"), never as a slug.
 3. **The matching concept doc** — for the framing you link to, not to repeat.
 
 If the UI does not match what you expected, the flow is wrong or the product changed.
@@ -76,10 +83,8 @@ Report the mismatch; do not write steps you have not verified.
 
 This is the easiest thing to get wrong. Concepts and references are `autogenerated`
 from their folders, so a new file appears on its own. **Flows are not.** After adding a
-flow, append its doc id to the matching domain's `items` array in BOTH:
-
-- `versioned_sidebars/version-3.0-sidebars.json`
-- `versioned_sidebars/version-3.1-sidebars.json`
+flow, append its doc id to the matching domain's `items` array in the sidebar file of
+every version you wrote to.
 
 ```json
 { "type": "category", "label": "Clinical", "key": "clinical-flows",
@@ -101,24 +106,24 @@ shared conventions rather than assuming.
 ### Creating a new flow
 
 1. Read the `create-patient` gold standard.
-2. Trace the task through `care_fe`, and the permission and API through `care`.
+2. Trace the task through `care_fe`, and the permission through `care`.
 3. Write to `flows/<domain>/<slug>.mdx`.
-4. Add the doc id to both sidebar files.
-5. Mirror to 3.1, then build.
+4. Add the doc id to the sidebar file of every version you wrote to.
+5. Mirror as the conventions describe, then build.
 
 ### Updating for a product change
 
 1. Decide what changed: the steps (UI moved, labels changed), the prerequisites
    (permission or configuration), or the outcome.
 2. Update only the affected sections; preserve the rest.
-3. Mirror to 3.1, build, and report what changed.
+3. Mirror as the conventions describe, build, and report what changed.
 
 ## Conventions (shared with concept and reference docs)
 
 Read `../care-concept-doc/references/conventions.md` before writing for: domains &
 slugs, the link rule, MDX safety (no `{#…}` heading ids; wrap `{ }` in backticks),
-3.0≡3.1 mirroring, and the `npm run build` (all locales) gate. That file is the single
-copy — do not fork a third version of it here.
+versioning and mirroring, and the `npm run build` (all locales) gate. That file is the
+single copy — do not fork a third version of it here, and do not restate its rules.
 
 ## Language