Merge pull request #92 from TaskarCenterAtUW/feat/akb-rag/3718-implement-mvp

Implement AKB RAG MVP

Author: uw-amy-bordenave

.github/agents/akb-reviewer.agent.md

@@ -0,0 +1,63 @@
+---
+description: "Use for reviewing Assistant Knowledge Base articles."
+name: "AKB Reviewer"
+tools: [read, search]
+argument-hint: "Path to a docs/assistant/**/*.md file to review, or the active article."
+---
+
+You are a specialist reviewer for TCAT Assistant Knowledge Base articles in `docs/assistant/`.
+
+Your job is to audit one assistant-layer Markdown file for schema compliance, retrieval quality, and assistant-safety. You review only. You do not edit files, rewrite articles, update `dispatch.md`, or approve content on behalf of TCAT staff.
+
+## Constraints
+
+- Review exactly one target article per invocation.
+- Read `docs/assistant/schema.md` fresh every time before assessing the article.
+- Treat the schema as the primary authority for required frontmatter and section structure.
+- Do not require `review_status: draft`; only require that `review_status`, if present, is valid per schema expectations.
+- Do not cross-reference or update `docs/assistant/dispatch.md`.
+- Do not invent product facts, policy interpretations, or missing article content.
+- Do not rewrite the full page. Provide findings only.
+
+## Review approach
+
+1. Identify the target file. If the user does not specify one, use the active file only if it is under `docs/assistant/`; otherwise ask for a path.
+2. Read `docs/assistant/schema.md` fresh.
+3. Read the target article.
+4. Evaluate the article in four passes:
+   - **Frontmatter**: required keys, valid enum-like values, plausible `last_reviewed`, and `assistant_behavior` shape.
+   - **Structure**: the nine required headings are present, spelled exactly, and appear in order.
+   - **Content quality**: `## Short Answer` is self-contained; `## What This Does Not Mean` contains substantive boundaries; `## How To Use This` matches the listed audiences; `## Assistant Guidance` gives concrete chatbot behavior.
+   - **Doc-type fit**: apply the appropriate check for `question`, `concept`, `workflow`, `policy`, or `glossary`.
+5. Keep `related_pages` checks narrow: verify the paths use `docs/`-relative `assistant/...` style and stay within the assistant layer. Do not verify them against `dispatch.md`.
+6. Classify findings as errors or warnings.
+
+## Doc-type checks
+
+- **question**: `## Short Answer` directly answers the question posed by the title.
+- **concept**: `## Short Answer` defines the concept clearly and precisely.
+- **workflow**: the page explains how the workflow should be used in practice, not just what it is.
+- **policy**: `## What This Means` states the practical consequences of the policy.
+- **glossary**: `## Short Answer` is a crisp definition of a single term.
+
+## Output format
+
+Use exactly these sections, in this order:
+
+### Summary
+One short paragraph on overall review status.
+
+### Errors
+Numbered list. If none, write `None.`
+
+### Warnings
+Numbered list. If none, write `None.`
+
+### Pass/Fail
+Write exactly one of:
+- `Pass`
+- `Fail`
+
+### Human follow-up
+- State whether the article appears ready for human review sign-off.
+- End with, in bold: `If you accept this review outcome, update docs/assistant/dispatch.md manually.`

.github/copilot-instructions.md

@@ -308,7 +308,7 @@ Invoke-Pester .\check-links.Tests.ps1 -ExcludeTag "Network" -Output Minimal # Sk
     - Use `- Guide` tag for regular guide pages
     - Use `- User Manual` tag for user manual index files (e.g., `user-manual/index.md`)
     - Use `- Tutorial` tag for tutorial guides (short tutorials focused on specific goals or use cases)
-2. **Other Tags**: Use additional tags for filtering; supported tags: "OSW 0.2", "OSW 0.3", "OSW 0.4", "Internal", "External", "Developer", "User"
+2. **Other Tags**: Use additional tags for filtering; supported tags: "OSW 0.2", "OSW 0.3", "OSW 0.4", "Internal", "External", "Developer", "User", "Assistant"
 3. **Abbreviations**: Wrap acronyms normally (e.g., "OSW", "TDEI", "JOSM"); abbreviations plugin auto-links them
 
 ### Frontmatter Title Pattern

.github/instructions/a11y.instructions.md

@@ -23,7 +23,7 @@ You are an expert in accessibility with deep software engineering expertise.
 - Use ARIA only when necessary (do not add ARIA to native elements when the native semantics already work).
 - Ensure correct accessible **name, role, value, states, and properties**.
 - All interactive elements are keyboard operable, with clearly visible focus, and no keyboard traps.
-- Do not claim the output is “fully accessible”.
+- Do not claim the output is "fully accessible".
 
 ## Inclusive language (MUST)
 
@@ -48,7 +48,7 @@ You are an expert in accessibility with deep software engineering expertise.
 ### Page title (SHOULD)
 
 - Set a descriptive `<title>`.
-- Prefer: “Unique page - section - site”.
+- Prefer: "Unique page - section - site".
 
 ## Keyboard and focus
 
@@ -236,7 +236,7 @@ If a component truly requires a two-dimensional layout for meaning/usage (e.g.,
 
 - The accessible name of each interactive element MUST contain the visible label.
     - If using `aria-label`, include the visual label text.
-- If multiple controls share the same visible label (e.g., many “Remove” buttons), use an `aria-label` that keeps the visible label text and adds context (e.g., “Remove item: Socks”).
+- If multiple controls share the same visible label (e.g., many "Remove" buttons), use an `aria-label` that keeps the visible label text and adds context (e.g., "Remove item: Socks").
 
 ## Forms
 

.github/instructions/content-style.instructions.md

@@ -1,6 +1,6 @@
 ---
 description: Editorial style guide for TCAT Wiki Markdown content
-applyTo: "docs/**/*.md"
+applyTo: "docs/{accessmap,aviv-scoutroute,events,josm,opensidewalks,os-connect,rapid,tdei,walksheds,workspaces}/**/*.md"
 ---
 
 <!-- @format -->

.github/prompts/akb-expand.prompt.md

@@ -0,0 +1,142 @@
+---
+description: Expand a minimal human-provided answer into a schema-compliant assistant knowledge base page
+agent: agent
+---
+
+<!-- @format -->
+
+# Expand Minimal Answer into Assistant Knowledge Base Page
+
+The user has provided a stub file path or slug and a minimal answer. Your job is to expand that answer into a complete, schema-compliant `docs/assistant/` knowledge base page. Follow every step in order. Do not skip or combine steps.
+
+## Inputs
+
+The user's message will contain:
+
+1. **Path or slug** — the unique slug or absolute or repo-relative path to the stub file in `docs/assistant/`, e.g. `docs/assistant/os-connect/how-do-i-report-an-error-in-os-connect-data.md`.
+2. **Minimal answer** — the human-provided seed content. This may be a few sentences, a list, or rough notes. Treat it as authoritative fact; do not contradict or discard it.
+
+If either input is missing, ask the user before proceeding.
+
+## Step 1 — Read the stub and the schema
+
+Read the stub file at the path given. Note all existing frontmatter fields; they take precedence over anything you infer.
+
+Then read the schema from `docs/assistant/schema.md`. Do not rely on your training data or cache for schema details — read it fresh, every time.
+
+## Step 2 — Infer frontmatter values
+
+Using the stub's existing frontmatter as the starting point, fill in or confirm every required field. Rules:
+
+- `title` — derive from the file name if not set: convert the kebab-case stem to title case, e.g. `how-do-i-report-an-error-in-os-connect-data` → `"How Do I Report an Error in OS-CONNECT Data?"`.
+- `slug` — use the file stem (kebab-case), unchanged.
+- `doc_type` — infer from directory or filename:
+  - Files in `questions/` subdirectories or whose names begin with interrogative words (`what`, `how`, `why`, `when`, `who`, `can`, `is`, `does`, `do`, `which`, `where`) → `question`.
+  - Files in `concepts/` or whose names name a system component → `concept`.
+  - Files in `workflows/` → `workflow`.
+  - Files in `policies/` → `policy`.
+  - Files in `glossary/` → `glossary`.
+- `products` — infer from the directory (`os-connect/` → `OS-CONNECT`, `workspaces/` → `Workspaces`, `accessmap/` → `AccessMap`, `walksheds/` → `Walksheds`, `tdei/` → `TDEI`, `support/` → all relevant products). Use the controlled list from the schema.
+- `audiences` — list several relevant audiences (`planner`, `jurisdiction`, `advocate`, `public`, `developer`, etc.) unless the content is clearly specialist-only.
+- `topics` — select from the controlled vocabulary in the schema. Add no more than five tags. Choose the most specific applicable tags.
+- `risk_level` — `low` by default. Use `medium` if the page touches ADA compliance, legal authority, data accuracy claims, or correction workflows. Use `high` only for pages with direct legal or safety consequences.
+- `authority_level` — `explanatory` by default. Use `draft` while content is in progress.
+- `review_status` — always set to `draft` for new pages.
+- `last_reviewed` — set to today's date in `YYYY-MM-DD` format.
+- `retrieval_priority` — `high` for the most important pages in a section, `medium` for most pages, `low` for supporting or supplementary content.
+- `assistant_behavior`:
+  - `allow_inference: false` for all pages (default).
+  - `requires_citation: true` for all pages (default).
+  - `abstain_if_missing_context: true` for pages where the correct answer depends on the user's jurisdiction, dataset version, or other context not provided; `false` otherwise.
+  - `do_not_claim` — list approximately one to five specific false or over-reaching claims an assistant might make that this page corrects. Phrase each as a complete declarative sentence. Leave empty (`[]`) if no obvious over-claims apply.
+- `related_pages` — list approximately two to five paths relative to `docs/` for closely related pages. Always include the section `index.md` (e.g. `assistant/os-connect/index.md`). Check `docs/assistant/dispatch.md` for available paths.
+
+## Step 3 — Write the nine body sections
+
+Write the full Markdown body in this exact order. Every heading must appear, spelled exactly as shown.
+
+### `# [Page Title]`
+The H1 must match the `title` frontmatter value exactly.
+
+### `## Short Answer`
+One to three short paragraphs. This is the text an assistant will surface directly in a reply. It must:
+- State the answer to the question (or define the concept/policy) clearly and completely.
+- Be self-contained — a reader with no other context should understand the answer.
+- Incorporate the user's provided minimal answer as its factual core. Do not paraphrase in ways that change meaning.
+- Stay under ~200 words.
+- Not contain "Yes" or "No" alone; provide a substantive statement.
+
+### `## Significance`
+One paragraph (2–4 sentences) explaining why this topic matters to planners, jurisdictions, advocates, the public, or other identified audiences. Focus on operational or civic importance. Do not use the heading "Why This Matters".
+
+### `## What This Means`
+Two to five bullet points (or a short paragraph) that unpack the answer in practical terms. If the page is a question, resolve the question definitively. If it is a concept, define it precisely. If it is a policy, state what follows from it.
+
+### `## What This Does Not Mean`
+Two to four bullet points of explicit boundaries, non-claims, and common misinterpretations. Each bullet corrects a plausible wrong conclusion a reader might draw. These become `do_not_claim` candidates — if a bullet is strong enough, add it to the frontmatter field too.
+
+### `## How To Use This`
+Audience-segmented guidance in one of these forms:
+- A short paragraph per audience (planners, jurisdictions, advocates, public, integrators) — only include audiences that actually apply.
+- A bulleted list of use cases, prefixed by the audience role in bold.
+
+### `## Example`
+One concrete, specific scenario. Name a real-sounding actor (a city planner, a transit agency GIS analyst, a disability advocate, a Safe Routes coordinator), pose the situation in one sentence, and show how this page's content resolves or addresses it.
+
+### `## Assistant Guidance`
+Two to five sentences of explicit behavioral instructions for chatbots consuming this page. Address:
+- When to cite this page.
+- Whether to abstain if context is missing.
+- Any `do_not_claim` items to watch for.
+- Whether to recommend the user consult a professional for legal, engineering, or safety questions.
+
+### `## Related Concepts`
+An unordered list of Markdown links to related pages. Format each as:
+`- [Link text](relative-path-from-this-file-to-target.md)`
+
+Always link the section index (e.g. `[OS-CONNECT knowledge base](index.md)`). Add two to four additional links to adjacent pages in `docs/assistant/dispatch.md` that are thematically related.
+
+## Step 4 — Validate before writing
+
+Before writing the file, check:
+
+1. All nine headings are present and in order.
+2. Every required frontmatter field is populated (no empty strings, no `null`).
+3. `review_status` is `draft`.
+4. `last_reviewed` is today's date.
+5. `do_not_claim` items (if any) are complete declarative sentences.
+6. `related_pages` paths use the `docs/`-relative format, not file-system paths.
+7. The `## Short Answer` does not contradict the user's minimal answer.
+8. No section is omitted, even if its content is brief.
+
+If any check fails, fix it before proceeding.
+
+## Step 5 — Write the file
+
+Write the completed file to the path given by the user. Overwrite the stub entirely.
+
+## Step 6 — Update dispatch.md
+
+Open `docs/assistant/dispatch.md`. Find the row for this file in the appropriate section table and change its `Status` from `stub` to `draft`. Use `replace_string_in_file` — do not rewrite the entire dispatch file.
+
+## Step 7 — Confirm
+
+Tell the user:
+- The file path written.
+- The `doc_type`, `risk_level`, and `retrieval_priority` values chosen and a very brief reasoning for each.
+- Any `do_not_claim` items added, so the user can verify they are accurate.
+- Whether `abstain_if_missing_context` was set to `true` and why.
+- The dispatch status updated from `stub` → `draft`.
+
+If the user's minimal answer left any factual gap that would require TCAT staff knowledge to fill (e.g. a specific correction timeline, a named contact, a URL), flag it explicitly so the user can supply it in a follow-up review and editing phase.
+
+---
+
+## Quality Rules (apply throughout)
+
+- **Never invent facts.** If the minimal answer does not state something, do not add it as though it were true. Use hedged language ("typically," "generally") only when the schema and product context genuinely support the hedge.
+- **Never contradict the minimal answer.** The user's seed content is authoritative.
+- **Preserve domain accuracy.** Do not rename, merge, or redefine TCAT products (TDEI, OS-CONNECT, Workspaces, AccessMap, Walksheds, OpenSidewalks, and AVIV ScoutRoute are each distinct).
+- **Keep the Short Answer self-contained.** A retrieval system may surface only that section.
+- **Match link paths to dispatch.md.** Only link to files that exist in the dispatch registry; do not invent file paths.
+- **Do not add extra headings** that duplicate or replace any of the nine required sections.

.github/prompts/akb-review.prompt.md

@@ -0,0 +1,19 @@
+---
+description: "Review an Assistant Knowledge Base article for schema compliance, structure, and quality."
+name: "akb-review"
+argument-hint: "Path to docs/assistant/**/*.md to review, or leave blank to review the active file"
+agent: "AKB Reviewer"
+---
+
+Review the specified Assistant Knowledge Base article in `docs/assistant/` against the schema in `docs/assistant/schema.md`.
+
+Requirements:
+
+- Review only; do not edit files.
+- Check frontmatter completeness and validity.
+- Check the nine required headings and their order.
+- Check `Short Answer`, boundary-setting, audience fit, and assistant guidance quality.
+- Apply the correct expectations for the article's `doc_type`.
+- Do not update `docs/assistant/dispatch.md`; remind the human to do that manually.
+
+If no file path is provided, review the active file only if it is under `docs/assistant/`. Otherwise, ask for a target file.

.github/workflows/build-and-deploy.yml

@@ -27,7 +27,33 @@ jobs:
           python-version: 3.x
           cache: pip
       - run: python -m pip install zensical
+      - run: |
+          mv docs/assistant /tmp/assistant-md
+          python3 - <<'EOF'
+          import os, shutil, re
+
+          src = '/tmp/assistant-md'
+          dst = 'docs/assistant'
+
+          for root, dirs, files in os.walk(src):
+              for fname in files:
+                  if not fname.endswith('.md'):
+                      continue
+                  src_file = os.path.join(root, fname)
+                  with open(src_file, encoding='utf-8') as f:
+                      content = f.read()
+                  if content.startswith('---'):
+                      end = content.find('---', 3)
+                      if end != -1:
+                          fm = content[3:end]
+                          if re.search(r'^\s*review_status\s*:\s*reviewed\s*$', fm, re.MULTILINE):
+                              rel = os.path.relpath(src_file, src)
+                              dst_file = os.path.join(dst, rel)
+                              os.makedirs(os.path.dirname(dst_file), exist_ok=True)
+                              shutil.copy2(src_file, dst_file)
+          EOF
       - run: zensical build --clean
+      - run: cp -r /tmp/assistant-md/. site/assistant/
       - uses: actions/upload-pages-artifact@v5
         with:
           path: site

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "files.associations": {
+        "*.md": "python-markdown"
+    }
+}

CHANGELOG.md

@@ -7,6 +7,14 @@ Changes to the TCAT Wiki are documented here.
 This project adheres to [Semantic Versioning](https://semver.org/) and
 [Conventional Commits](https://www.conventionalcommits.org/).
 
+## v12.0.0 (2026-06-23)
+
+### Features
+
+- **Core**: Add assistant knowledge base
+- **Core**: Update build and deployment workflow to publish Assistant Knowledge Base pages as both user-facing Zensical-built HTML and raw Markdown
+- **Core**: Upgrade Zensical to 0.0.46
+
 ## v11.12.1 (2026-06-02)
 
 ### Fixes

CONTRIBUTING.md

@@ -14,7 +14,7 @@ This guide explains how to contribute to the TCAT Wiki.
 
 Note that, while minor external contributions are welcome, this guide is primarily intended for use by TCAT/GS staff.
 
-_For a list of all guides on the TCAT Wiki, refer to the [Guides List](guides-list/index.md)._
+_For a list of all guides on the TCAT Wiki, refer to the [Guides List](https://taskarcenteratuw.github.io/tcat-wiki/guides-list/)._
 
 ---
 
@@ -127,6 +127,8 @@ This section of the guide explains how to set up a Windows environment for contr
 
         5. [Even Better TOML](https://marketplace.visualstudio.com/items?itemName=tamasfe.even-better-toml)
 
+        6. [Zensical Studio](https://marketplace.visualstudio.com/items?itemName=zensical.zensical-studio)
+
 2. Clone the repository
 
     ```powershell