Fixes

Author: MelbourneDeveloper

.claude/skills/spec-check/SKILL.md

@@ -3,17 +3,17 @@ name: submit-pr
 description: Creates a pull request with a well-structured description after verifying CI passes. Use when the user asks to submit, create, or open a pull request.
 disable-model-invocation: true
 ---
-<!-- agent-pmo:d58c330 -->
+<!-- agent-pmo:29b9dcf -->
 
 # Submit PR
 
 Create a pull request for the current branch with a well-structured description.
 
 ## Steps
 
-1. Run `make ci` -- must pass completely before creating PR
+1. Run `make ci` — must pass completely before creating PR
 2. **Generate the diff against main.** Run `git diff main...HEAD > /tmp/pr-diff.txt` to capture the full diff between the current branch and the head of main. This is the ONLY source of truth for what the PR contains. **Warning:** the diff can be very large. If the diff file exceeds context limits, process it in chunks (e.g., read sections with `head`/`tail` or split by file) rather than trying to load it all at once.
-3. **Derive the PR title and description SOLELY from the diff.** Read the diff output and summarize what changed. Ignore commit messages, branch names, and any other metadata -- only the actual code/content diff matters.
+3. **Derive the PR title and description SOLELY from the diff.** Read the diff output and summarize what changed. Ignore commit messages, branch names, and any other metadata — only the actual code/content diff matters.
 4. Write PR body using the template in `.github/pull_request_template.md`
 5. Fill in (based on the diff analysis from step 3):
    - TLDR: one sentence
@@ -27,7 +27,7 @@ Create a pull request for the current branch with a well-structured description.
 ## Rules
 
 - Never create a PR if `make ci` fails
-- PR description must be specific and tight -- no vague placeholders
+- PR description must be specific and tight — no vague placeholders
 - Link to the relevant GitHub issue if one exists
 
 ## Success criteria

.claude/skills/submit-pr/SKILL.md

@@ -1,45 +1,71 @@
 ---
 name: upgrade-packages
-description: Upgrade all dependencies/packages to their latest versions for C#/.NET. Use when the user says "upgrade packages", "update dependencies", "bump versions", "update packages", or "upgrade deps".
+description: Upgrade all dependencies/packages to their latest versions for C#/.NET and Python. Use when the user says "upgrade packages", "update dependencies", "bump versions", "update packages", or "upgrade deps".
 argument-hint: "[--check-only] [--major] [package-name]"
 ---
-<!-- agent-pmo:d58c330 -->
+<!-- agent-pmo:29b9dcf -->
 
 # Upgrade Packages
 
-Upgrade all project dependencies to their latest compatible (or latest major, if `--major`) versions.
+Upgrade all project dependencies to their latest compatible (or latest major, if `--major`) versions for HealthcareSamples (C#/.NET primary, Python embedding service + scripts).
 
 ## Arguments
 
-- `--check-only` -- List outdated packages without upgrading. Stop after Step 2.
-- `--major` -- Include major version bumps (breaking changes). Without this flag, stay within semver-compatible ranges.
+- `--check-only` — List outdated packages without upgrading. Stop after Step 2.
+- `--major` — Include major version bumps (breaking changes). Without this flag, stay within semver-compatible ranges.
 - Any other argument is treated as a specific package name to upgrade (instead of all packages).
 
-## Step 1 -- Detect language and package manager
+## Step 1 — Detect language and package manager
 
-This is a C#/.NET repo. Manifest files:
-- `HealthcareSamples.sln`
-- `Directory.Build.props`
-- Individual `.csproj` files across Clinical, Scheduling, ICD10, Dashboard, and Shared projects
+Inspect the repo for these manifest files:
 
-## Step 2 -- List outdated packages
+| Manifest file | Language | Package manager |
+|---|---|---|
+| `*.csproj` / `*.sln` | C# / .NET | NuGet (dotnet) |
+| `Directory.Build.props` | C# / .NET | NuGet (dotnet) — central version pinning |
+| `requirements.txt` | Python (ICD10/embedding-service, ICD10/scripts/CreateDb) | pip |
 
+This repo uses both. Process .NET first, then Python.
+
+## Step 2 — List outdated packages
+
+Run the appropriate command BEFORE upgrading anything. Show the user what will change.
+
+### C# / .NET (NuGet)
 ```bash
-dotnet list package --outdated
+dotnet list HealthcareSamples.sln package --outdated
 ```
-
-For transitive dependencies too: `dotnet list package --outdated --include-transitive`
+For transitive dependencies too: `dotnet list HealthcareSamples.sln package --outdated --include-transitive`
 
 **Read the docs:** https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-list-package
 
+### Python (pip)
+The Python pieces use plain `requirements.txt` files. Install each in a venv and run `pip list --outdated`:
+```bash
+# embedding service
+python -m venv /tmp/embedding-venv
+/tmp/embedding-venv/bin/pip install -r ICD10/embedding-service/requirements.txt
+/tmp/embedding-venv/bin/pip list --outdated
+
+# DB scripts
+python -m venv /tmp/scripts-venv
+/tmp/scripts-venv/bin/pip install -r ICD10/scripts/CreateDb/requirements.txt
+/tmp/scripts-venv/bin/pip list --outdated
+```
+
+**Read the docs:** https://pip.pypa.io/en/stable/cli/pip_install/#cmdoption-U
+
 If `--check-only` was passed, **stop here** and report the outdated list.
 
-## Step 3 -- Read the official upgrade docs
+## Step 3 — Read the official upgrade docs
 
 **Before running any upgrade command, you MUST fetch and read the official documentation URL listed above for the detected package manager.** Use WebFetch to retrieve the page. This ensures you use the correct flags and understand the behavior. Do not guess at flags or options from memory.
 
-## Step 4 -- Upgrade packages
+## Step 4 — Upgrade packages
+
+Run the upgrade. If a specific package name was given as an argument, upgrade only that package.
 
+### C# / .NET (NuGet)
 There is NO single `dotnet upgrade-all` command. You must upgrade each package individually:
 ```bash
 # For each outdated package from Step 2:
@@ -58,7 +84,17 @@ dotnet outdated --upgrade
 ```
 **Read the docs:** https://github.com/dotnet-outdated/dotnet-outdated
 
-## Step 5 -- Verify the upgrade
+### Python (pip)
+For `requirements.txt`:
+```bash
+/tmp/embedding-venv/bin/pip install --upgrade -r ICD10/embedding-service/requirements.txt
+/tmp/embedding-venv/bin/pip freeze > ICD10/embedding-service/requirements.txt
+
+/tmp/scripts-venv/bin/pip install --upgrade -r ICD10/scripts/CreateDb/requirements.txt
+/tmp/scripts-venv/bin/pip freeze > ICD10/scripts/CreateDb/requirements.txt
+```
+
+## Step 5 — Verify the upgrade
 
 After upgrading, run the project's build and test suite to confirm nothing broke:
 
@@ -68,17 +104,17 @@ make ci
 
 If tests fail:
 1. Read the failure output carefully
-2. Check the changelog / migration guide for the upgraded packages
+2. Check the changelog / migration guide for the upgraded packages (fetch the release notes URL if available)
 3. Fix breaking changes in the code
 4. Re-run tests
-5. If stuck after 3 attempts on the same failure, report it to the user
+5. If stuck after 3 attempts on the same failure, report it to the user with the error details and the package that caused it
 
-## Step 6 -- Report
+## Step 6 — Report
 
 Provide a summary:
 
 - Packages upgraded (old version -> new version)
-- Packages skipped (and why)
+- Packages skipped (and why, e.g., major version bump without `--major` flag)
 - Build/test result after upgrade
 - Any breaking changes that were fixed
 - Any packages that could not be upgraded (with error details)
@@ -90,8 +126,8 @@ Provide a summary:
 - **Always run tests after upgrading** to catch breakage immediately
 - **Never remove packages** unless they were explicitly deprecated and replaced
 - **Never downgrade packages** unless rolling back a broken upgrade
-- **Never modify lockfiles manually** -- let the package manager regenerate them
-- **Commit nothing** -- leave changes in the working tree for the user to review
+- **Never modify lockfiles manually** — let the package manager regenerate them
+- **Commit nothing** — leave changes in the working tree for the user to review
 
 ## Success criteria
 

.claude/skills/upgrade-packages/SKILL.md

@@ -2,7 +2,7 @@
 name: website-audit
 description: Audits a website for SEO, AI search performance, structured data, mobile usability, broken links, and social media cards. Fixes issues found. Use when the user mentions "audit website", "SEO", "fix search ranking", "AI search", "structured data", "social media cards", or "website performance".
 ---
-<!-- agent-pmo:d58c330 -->
+<!-- agent-pmo:29b9dcf -->
 
 # Website Audit
 
@@ -26,52 +26,54 @@ Audit Progress:
 - [ ] Step 12: Report findings
 ```
 
-- Check the outputted HTML/CSS/JavaScript AFTER the website is generated by the static content generator. - Don't just check the static content before the website is generated.
+- Check the outputted HTML/CSS/JavaScript AFTER the website is generated by the static content generator.  - Don't just check the static content before the website is generated. 
 - Fix issues at the core where the static content templates are stored - not in the outputted HTML (e.g. _site)
 - Never manually edit the generated website content directly
 
-## Step 1 -- Read guidelines
+## Step 1 — Read guidelines
 
 Fetch and read each of these before auditing. These are the authoritative references for every step that follows.
 
 - [Google's guidance on using generative AI content](https://developers.google.com/search/docs/fundamentals/using-gen-ai-content)
 - [Top ways to ensure content performs well in Google's AI experiences](https://developers.google.com/search/blog/2025/05/succeeding-in-ai-search)
 - [SEO Starter Guide](https://developers.google.com/search/docs/fundamentals/seo-starter-guide)
 
+If the repo has a business plan doc, take it into account
+
 Identify the website source files in the repo. Determine the framework (static site generator, Next.js, Hugo, etc.) so you know where to find templates, metadata, and content.
 
-## Step 2 -- Audit AI search readiness
+## Step 2 — Audit AI search readiness
 
 Apply the guidance from the AI search article. Check:
 
-1. **Content quality** -- Is content original, expert-level, and comprehensive? Flag thin or duplicated pages.
-2. **Clear structure** -- Do pages use descriptive headings, lists, and concise answers to likely questions?
-3. **Entity clarity** -- Are key terms, products, and concepts defined clearly so AI can extract them?
-4. **Freshness signals** -- Are dates, update timestamps, and authorship present?
+1. **Content quality** — Is content original, expert-level, and comprehensive? Flag thin or duplicated pages.
+2. **Clear structure** — Do pages use descriptive headings, lists, and concise answers to likely questions?
+3. **Entity clarity** — Are key terms, products, and concepts defined clearly so AI can extract them?
+4. **Freshness signals** — Are dates, update timestamps, and authorship present?
 
 Fix issues directly in the source files. For each fix, note what changed and why.
 
-## Step 3 -- Audit SEO and keywords
+## Step 3 — Audit SEO and keywords
 
 1. Search [Google Trends](https://trends.google.com/home) for trending keywords related to the website's content.
 2. Review each page's `<title>`, `<meta name="description">`, and `<h1>` tags.
-3. Check for keyword opportunities -- can trending terms be naturally inserted into headings, descriptions, or body content?
+3. Check for keyword opportunities — can trending terms be naturally inserted into headings, descriptions, or body content?
 4. Verify each page has a unique, descriptive title (50-60 chars) and meta description (150-160 chars).
 5. Check image `alt` attributes describe the image content and include relevant keywords where natural.
 
 Apply the [SEO Starter Guide](https://developers.google.com/search/docs/fundamentals/seo-starter-guide) principles. Fix issues directly.
 
-## Step 4 -- Audit crawling and indexing
+## Step 4 — Audit crawling and indexing
 
 Reference: [Overview of crawling and indexing topics](https://developers.google.com/search/docs/crawling-indexing)
 
-1. **robots.txt** -- Locate and review it. Verify it doesn't block important pages. Reference: [robots.txt spec](https://developers.google.com/search/docs/crawling-indexing/robots-txt)
-2. **Sitemap** -- Locate the sitemap (or sitemap index). Verify all important pages are listed and no dead URLs are included. Reference: [Sitemap guidelines](https://developers.google.com/search/docs/crawling-indexing/sitemaps/large-sitemaps)
-3. **Meta robots tags** -- Check for unintended `noindex` or `nofollow` directives on pages that should be indexed.
+1. **robots.txt** — Locate and review it. Verify it doesn't block important pages. Reference: [robots.txt spec](https://developers.google.com/search/docs/crawling-indexing/robots-txt)
+2. **Sitemap** — Locate the sitemap (or sitemap index). Verify all important pages are listed and no dead URLs are included. Reference: [Sitemap guidelines](https://developers.google.com/search/docs/crawling-indexing/sitemaps/large-sitemaps)
+3. **Meta robots tags** — Check for unintended `noindex` or `nofollow` directives on pages that should be indexed.
 
 Note: robots.txt and sitemaps are often auto-generated. If so, check the generator config rather than the output file.
 
-## Step 5 -- Audit broken links and canonicalization
+## Step 5 — Audit broken links and canonicalization
 
 Reference: [What is canonicalization](https://developers.google.com/search/docs/crawling-indexing/canonicalization)
 
@@ -80,7 +82,7 @@ Reference: [What is canonicalization](https://developers.google.com/search/docs/
 3. Check for duplicate content accessible via multiple URLs (with/without trailing slash, www vs non-www).
 4. Verify redirects use 301 (permanent) not 302 (temporary) where appropriate.
 
-## Step 6 -- Audit mobile usability
+## Step 6 — Audit mobile usability
 
 Reference: [Mobile-first indexing best practices](https://developers.google.com/search/docs/crawling-indexing/mobile/mobile-sites-mobile-first-indexing)
 
@@ -89,7 +91,7 @@ Reference: [Mobile-first indexing best practices](https://developers.google.com/
 3. Verify touch targets are adequately sized (min 48x48px).
 4. Check font sizes are readable without zooming (min 16px body text).
 
-## Step 7 -- Audit structured data
+## Step 7 — Audit structured data
 
 Reference: [Structured data guidelines](https://developers.google.com/search/docs/appearance/structured-data/sd-policies)
 
@@ -102,7 +104,7 @@ Reference: [Structured data guidelines](https://developers.google.com/search/doc
    - **FAQ** for pages with question/answer content
 4. Validate JSON-LD syntax is correct.
 
-## Step 8 -- Audit social media cards
+## Step 8 — Audit social media cards
 
 Reference: [Implementing Social Media Preview Cards](https://documentation.platformos.com/use-cases/implementing-social-media-preview-cards)
 
@@ -124,31 +126,31 @@ Ensure that all claims are backed up with a link to a reputable source. As an ex
 
 Search for the authoritative URL and add a link to the URL. If it is not available, change the claim to something that can be substatiated.
 
-## Step 10 -- Audit Design Compliance
+## Step 10 — Audit Design Compliance
 
 Read the design system docs and view the design screens in the designsystem folder.
 
-## Step 11 -- Test with Playwright
+## Step 11 — Test with Playwright
 
 Build and run the website locally using `make website-run` (or the project's equivalent dev server command).
 
 **Desktop tests (1280x720):**
 
-1. Navigate to the homepage -- take a screenshot.
-2. Navigate to each major section -- verify pages load without errors.
+1. Navigate to the homepage — take a screenshot.
+2. Navigate to each major section — verify pages load without errors.
 3. Check the browser console for JavaScript errors.
 4. Verify all navigation links work.
 
 **Mobile tests (375x667, iPhone SE):**
 
 1. Resize the browser to mobile dimensions.
-2. Navigate to the homepage -- take a screenshot.
+2. Navigate to the homepage — take a screenshot.
 3. Verify the layout is responsive (no horizontal overflow, readable text).
 4. Test navigation menu (hamburger menu if applicable).
 
 If any page fails to load or has console errors, fix the issue and retest.
 
-## Step 12 -- Report findings
+## Step 12 — Report findings
 
 Summarize the audit results:
 
@@ -170,8 +172,8 @@ Summarize the audit results:
 
 ## Rules
 
-- **Fix issues directly** -- don't just report them. Only flag issues as warnings when they require human judgment (e.g., content tone, keyword selection).
-- **One step at a time** -- complete each step before moving to the next.
-- **Preserve existing content** -- improve structure and metadata without rewriting the author's voice.
-- **No keyword stuffing** -- keywords must read naturally in context.
-- **Respect the framework** -- edit templates/configs, not generated output files.
+- **Fix issues directly** — don't just report them. Only flag issues as warnings when they require human judgment (e.g., content tone, keyword selection).
+- **One step at a time** — complete each step before moving to the next.
+- **Preserve existing content** — improve structure and metadata without rewriting the author's voice.
+- **No keyword stuffing** — keywords must read naturally in context.
+- **Respect the framework** — edit templates/configs, not generated output files.

.claude/skills/website-audit/SKILL.md

@@ -1,4 +1,4 @@
-<!-- agent-pmo:d58c330 -->
+<!-- agent-pmo:29b9dcf -->
 
 # Single Source of Truth
 

.clinerules/00-read-instructions.md

@@ -1,4 +1,4 @@
-<!-- agent-pmo:d58c330 -->
+<!-- agent-pmo:29b9dcf -->
 
 @CLAUDE.md
 

.github/copilot-instructions.md

@@ -1,4 +1,4 @@
-# agent-pmo:d58c330
+# agent-pmo:29b9dcf
 
 # =============================================================================
 # UNIVERSAL

.gitignore

@@ -1,4 +1,4 @@
-<!-- agent-pmo:d58c330 -->
+<!-- agent-pmo:29b9dcf -->
 
 # Single Source of Truth
 

AGENTS.md

@@ -1,4 +1,4 @@
-<!-- agent-pmo:d58c330 -->
+<!-- agent-pmo:29b9dcf -->
 
 # HealthcareSamples -- Agent Instructions