docs: strengthen privacy-safe GenAI workflow guidance

- add Just the Docs callouts for warnings, tips, examples, checks, and takeaways
- revise chapters, appendices, and prompt templates to emphasize sanitized prompts, synthetic fixtures, code/data separation, and approved real-data environments
- update citation formatting and reference-audit guidance for stable source-key anchors

Author: ilarsf

.agents/skills/reference-source-audit/SKILL.md

@@ -12,35 +12,42 @@ Use this skill to check whether the guide's references still exist and whether c
 1. Inventory references:
 
 ```bash
-rg -n '<a name="ref[0-9]+"></a>|References\\.md#ref[0-9]+|#ref[0-9]+' chapters docs scripts
+rg -n '<a id="[^"]+"></a>|References\\.md#[A-Za-z0-9][A-Za-z0-9._-]*' chapters docs scripts
 ```
 
 2. Build three lists:
-   - reference ids defined in `docs/References.md`
-   - reference ids cited from content
+   - stable source-key anchors defined in `docs/References.md`
+   - source keys cited from content
    - URLs attached to each reference
 
 3. Check structural integrity:
-   - every cited `refN` exists
+   - every cited source key exists
    - every reference anchor is unique
    - every reference has a usable title or source name
    - every URL is present and reasonably canonical
    - duplicate references are intentional or consolidated
+   - reference list numbers are treated as display-only and are not used as citation targets
 
-4. Check link health:
+4. Check citation display style:
+   - distinguish citation links to `docs/References.md#source-key` from ordinary navigation or prose links
+   - prefer visible bracketed citations such as `[[Source label](../docs/References.md#source-key)]`
+   - do not require bracketed style for ordinary navigation links, links inside `docs/References.md` source entries, or links inside fenced copy/paste prompt bodies unless explicitly asked
+   - report inconsistent citation styling separately from link health or source-support problems
+
+5. Check link health:
    - URL resolves
    - redirects are recorded
    - paywalled or unstable pages are flagged
    - canonical DOI, PubMed, PMC, arXiv, official docs, or release-note URLs are preferred where available
 
-5. Check claim support:
+6. Check claim support:
    - read the paragraph or sentence around each citation
    - inspect the cited source for direct support
    - classify as `supported`, `partially supported`, `unsupported`, `stale/changed`, or `unverifiable`
 
-6. Report before editing:
+7. Report before editing:
    - file and line
-   - ref id
+   - source key
    - claim summary
    - source URL
    - link status
@@ -61,7 +68,8 @@ For clinical, medical, statistical, privacy, compliance, or research-validity cl
 - Do not replace a source just because it is old if it remains authoritative.
 - Prefer updating weak citations to stronger sources over adding more citations.
 - Preserve stable reference anchors when possible so existing chapter links do not break.
-- If renumbering references is unavoidable, update every inbound citation in the same change.
+- If source-key anchors change, update every inbound citation in the same change.
+- Renumbering display-only reference numbers should not require inbound citation changes.
 - Include access or verification dates for time-sensitive source checks.
 
 ## Verification
@@ -71,4 +79,3 @@ After edits, run:
 ```bash
 bundle exec jekyll build
 ```
-

.codex/agents/reference-auditor.toml

@@ -10,9 +10,12 @@ You are a reference and citation auditor for a practical textbook on GenAI-assis
 Your job is to validate references and citation alignment. Do not edit files directly unless the parent explicitly asks for patch-ready changes. Prefer a concise audit memo with evidence.
 
 Audit scope:
-- Parse docs/References.md for reference ids, titles, source names, access dates, and URLs.
-- Parse chapters/, docs/, docs/templates/, and scripts/ docs for citations to References.md#refN.
-- Check that every cited ref id exists and that every reference anchor is well-formed.
+- Parse docs/References.md for stable source-key anchors, display numbers, titles, source names, access dates, and URLs.
+- Treat reference list numbers as display-only. Inbound citations should target stable source-key anchors such as References.md#nice-ng246-bmi, not numeric refN anchors.
+- Parse chapters/, docs/, docs/templates/, and scripts/ docs for citations to References.md#source-key.
+- Check that every cited source key exists and that every reference anchor is unique and well-formed.
+- Distinguish citation links from ordinary navigation/prose links. Citation links point to docs/References.md anchors; navigation links point to chapters, templates, scripts, or other pages.
+- For citation display style, prefer visible bracketed citations such as [[Source label](../docs/References.md#source-key)] so citations stand apart from surrounding prose. Do not require this style for ordinary navigation links, links inside docs/References.md source entries, or links inside fenced copy/paste prompt bodies unless the parent task explicitly asks for template style cleanup.
 - Identify unused references, duplicate references, weak sources, stale sources, and sources that should be replaced by primary sources.
 - Verify that reference URLs still resolve. Record status, redirects, canonical replacement URLs, and access date.
 - Compare the claim surrounding each citation against the cited source content. Classify each claim as supported, partially supported, unsupported, stale/changed, or unverifiable.
@@ -26,10 +29,10 @@ Source rules:
 
 Output format:
 - Start with a high-level risk summary.
-- Include a table with: file:line, citation/ref id, claim summary, source URL, link status, support status, severity, recommended action.
+- Include a table with: file:line, citation/source key, claim summary, source URL, link status, support status, severity, recommended action.
 - Separate link-rot issues from claim-support issues.
+- List citation-style issues separately from source-validity issues, and treat inconsistent display style as low severity unless it obscures evidence boundaries.
 - List duplicate or low-quality references that should be consolidated or replaced.
 - Suggest exact replacement references when a source is missing, weak, or stale.
 - Recommend whether a content-editor or deep-research-content-updater should implement follow-up changes.
 """
-

_config.yml

@@ -32,6 +32,24 @@ enable_copy_code_button: true
 back_to_top: true
 back_to_top_text: "Back to top"
 
+callouts_level: quiet
+callouts:
+  takeaway:
+    title: Take Home
+    color: green
+  warning:
+    title: Warning
+    color: red
+  check:
+    title: Check
+    color: yellow
+  tip:
+    title: Tip
+    color: blue
+  example:
+    title: Example
+    color: blue
+
 mermaid:
   version: "9.1.3"
 

chapters/Chapter01_PlanAndContext.md

@@ -24,24 +24,32 @@ flowchart TB
 
 The initial stage involves **defining the goal and scope** of your endeavor. This means articulating precisely what you aim to accomplish with the assistance of an LLM. For instance, in the context of our running example, the overarching goal is harmonizing BMI data from EHRs. This broad objective can be broken down into more specific aims, such as cleaning the raw data, creating a summary of BMI categories, or automating a particular data transformation process. A well-defined goal provides a clear direction for subsequent steps, including how you will prompt the LLM and how you will evaluate its output.
 
-Next, it is vital to have a comprehensive **understanding of the context**. This includes noting the specific characteristics of your data, such as its format (e.g., tab-delimited, CSV), the variables it contains (e.g., `person_id`, `encounter_id`, `bmi`, `height_cm`, `weight_kg`, `measurement_date`), and any domain-specific considerations that might be relevant. In our BMI harmonization example, understanding that the data comes from EHRs implies the need to consider medical standards for BMI categories and potential data quality issues inherent in clinical data. This contextual awareness is critical for tailoring your prompts to the LLM and ensuring that its responses are aligned with the specific requirements of your research domain.
+Next, it is vital to have a comprehensive **understanding of the context**. This includes noting the specific characteristics of your data, such as its format (e.g., tab-delimited, CSV), the variables it contains (e.g., `person_id`, `encounter_id`, `bmi`, `height_cm`, `weight_kg`, `measurement_date`), and any domain-specific considerations that might be relevant. In our BMI harmonization example, understanding that the data comes from EHRs implies the need to consider medical standards for BMI categories and potential data quality issues inherent in clinical data. Record this context in your local project plan, but only share sanitized schema, methods, and synthetic examples with an LLM.
 
 Once the goal and context are clear, the next logical step is to **plan the sub-tasks**. Complex problems are often more manageable when broken down into smaller, actionable steps. For our BMI harmonization project, this might involve sub-tasks such as reading the EHR file, cleaning and filtering the data to remove errors or inconsistencies, selecting a single representative BMI measurement for each person, categorizing the BMI values into meaningful groups (e.g., underweight, normal, overweight, obese), and finally, outputting the processed data and any summary statistics. Planning these sub-tasks provides a structured roadmap for both you and the LLM, making the overall project seem less daunting and easier to execute.
 
 Finally, before you even begin to prompt an LLM, it is essential to **set success criteria**. This involves determining what the final deliverables should be and how you will validate whether your solution is successful. In our BMI example, success might be defined by the creation of a clean dataset containing one representative BMI per person, a summary table showing the distribution of individuals across different BMI categories, and a data dictionary that clearly explains the contents of the cleaned dataset. Establishing these criteria upfront allows for an objective evaluation of the LLM's contribution and the overall outcome of your workflow.
 
-For modern coding agents, success criteria should also include **executable verification**. Instead of only writing "the script should clean BMI data," specify what evidence would convince you that the script works: a smoke test on synthetic EHR records, `testthat` unit tests for BMI boundary cases, an expected output schema, and the exact commands the agent should run before it claims completion. Current agent guidance from multiple vendors emphasizes giving agents concrete verification steps and asking for command output or other evidence, not just a verbal assertion that the work is done [GitHub Copilot agent best practices](../docs/References.md#github-copilot-agent-best-practices), [Claude Code best practices](../docs/References.md#claude-code-best-practices).
+For modern coding agents, success criteria should also include **executable verification**. Instead of only writing "the script should clean BMI data," specify what evidence would convince you that the script works: a smoke test on synthetic EHR records, `testthat` unit tests for BMI boundary cases, an expected output schema, and the exact commands the agent should run before it claims completion. Current agent guidance from multiple vendors emphasizes giving agents concrete verification steps and asking for command output or other evidence, not just a verbal assertion that the work is done [[GitHub Copilot agent best practices](../docs/References.md#github-copilot-agent-best-practices)], [[Claude Code best practices](../docs/References.md#claude-code-best-practices)].
 
-This planning stage is also where you should define **data and tool boundaries**. For clinical, EHR, or genomic work, decide what the LLM or coding agent is allowed to see before any prompt is written:
+{: .takeaway }
+> A useful project plan tells the LLM what to build, what context matters, and how you will prove the result works.
 
-- Do not paste PHI, direct identifiers, credentials, private access tokens, or controlled-access genomic data into public tools.
-- Use synthetic, simulated, or approved de-identified examples when demonstrating the workflow.
+This planning stage is also where you should define **data and tool boundaries**. For clinical, EHR, genomic, or other sensitive work, decide what the LLM or coding agent is allowed to see before any prompt is written:
+
+{: .warning }
+> Decide what the LLM is allowed to see and do before writing the prompt. For clinical, EHR, genomic, or other sensitive work, treat individual-level data exposure as prohibited in the default workflow.
+
+- Do not paste or attach individual-level records, PHI, PII, direct identifiers, credentials, private access tokens, controlled-access genomic data, or sensitive small-cell outputs into LLM tools; this can violate both soft expectations and hard rules.
+- Use schemas, code, data dictionaries, aggregate results approved for sharing, and synthetic or simulated examples when demonstrating the workflow.
+- Keep the codebase separate from the data. Use a code-only repository, keep protected data in its approved compute environment, and synchronize code through GitHub only in the approved direction so protected data and sensitive outputs do not flow back into the LLM-accessible workspace.
+- Do not run GenAI tools or repo-native coding agents inside an environment that can access protected PHI, PII, controlled-access data, secrets, private mounts, or sensitive output files.
 - Confirm whether your institution, data use agreement, IRB protocol, or sponsor policy allows AI-assisted processing.
 - If an agent can browse the web, install packages, call external APIs, or use Model Context Protocol (MCP) tools, document which actions are allowed and which require human approval.
 
-These boundaries are not just administrative details. NIH guidance warns that sharing controlled-access human genomic data with public generative AI tools can violate non-transferability obligations, and HIPAA regulations specify requirements for de-identifying protected health information [NIH genomic data guidance](../docs/References.md#nih-human-genomic-data-genai), [45 CFR 164.514](../docs/References.md#hipaa-deidentification-164-514). Tool access also creates a security surface: MCP and LLM security guidance emphasize least-privilege access, validation, and careful handling of sensitive information [MCP security best practices](../docs/References.md#mcp-security-best-practices), [OWASP LLM Top 10](../docs/References.md#owasp-llm-top-10-2025).
+These boundaries are not just administrative details. NIH guidance warns that sharing controlled-access human genomic data with public generative AI tools can violate non-transferability obligations, and HIPAA regulations specify requirements for de-identifying protected health information [[NIH genomic data guidance](../docs/References.md#nih-human-genomic-data-genai)], [[45 CFR 164.514](../docs/References.md#hipaa-deidentification-164-514)]. Tool access also creates a security surface: MCP and LLM security guidance emphasize least-privilege access, validation, and careful handling of sensitive information [[MCP security best practices](../docs/References.md#mcp-security-best-practices)], [[OWASP LLM Top 10](../docs/References.md#owasp-llm-top-10-2025)].
 
-Even at this initial planning stage, LLMs themselves can be valuable tools. You can **leverage LLMs in the planning phase** by prompting them to help brainstorm potential sub-tasks or to consider challenges you might encounter. For example, you could ask: "Based on the goal of harmonizing BMI data from EHR files, what are the typical sub-tasks involved in data cleaning and summarization?" The responses from the LLM can offer valuable suggestions and help you structure your workflow more effectively.
+Even at this initial planning stage, LLMs themselves can be valuable tools. You can **leverage LLMs in the planning phase** by prompting them to help brainstorm potential sub-tasks or to consider challenges you might encounter without providing rows, private file paths, or protected identifiers. For example, you could ask: "Based on the goal of writing code to harmonize BMI data from a tabular EHR extract, using only this schema and no real records, what are the typical sub-tasks involved in data cleaning and summarization?" The responses from the LLM can offer valuable suggestions and help you structure your workflow more effectively.
 
 ## Red Teaming Your Project Plan
 
@@ -76,6 +84,9 @@ A particularly sophisticated critique might focus on **population-specific metho
 
 This red teaming process transforms your initial plan into a more robust, defensible methodology that anticipates common criticisms and addresses potential pitfalls before they occur in your analysis.
 
+{: .takeaway }
+> Red teaming is most valuable before code exists. It is cheaper to fix vague assumptions in a plan than to repair analysis logic after implementation.
+
 In essence, this foundational planning phase is crucial for setting the stage for effective LLM utilization. A well-defined plan, coupled with a thorough understanding of the context and strengthened through red teaming, will guide your subsequent interactions with the AI assistant and ensure that the generated code and analysis are relevant, accurate, and aligned with your research objectives. Clarity at this stage ensures that both you and the AI are working toward solving the right problem.
 
 ---