Refresh May documentation bundle

README.md

@@ -88,8 +88,74 @@ Rule:
 
 More context:
 - [release_bundle/2026-04_newsletter_launch/START_HERE.md](release_bundle/2026-04_newsletter_launch/START_HERE.md)
+- [release_bundle/2026-05_newsletter_cost_optimization/CUSTOMER_COMPANION.md](release_bundle/2026-05_newsletter_cost_optimization/CUSTOMER_COMPANION.md)
+- [release_bundle/2026-05_newsletter_cost_optimization/NEWSLETTER_SYSTEM_RELEASE_NOTES.md](release_bundle/2026-05_newsletter_cost_optimization/NEWSLETTER_SYSTEM_RELEASE_NOTES.md)
 - [release_bundle/2026-02_newsletter_launch/public/START_HERE.md](release_bundle/2026-02_newsletter_launch/public/START_HERE.md)
 
+## Current Release Bundle: May 2026
+
+The May 2026 bundle is the current public companion for the cost-aware newsletter
+generation work. It is meant to help a developer answer three practical
+questions:
+
+1. How do I generate a newsletter with fewer wasted tokens?
+2. How do I optimize a similar agentic workflow without lowering quality?
+3. What changed across the newsletter generation system beyond the May issue
+  itself?
+
+Start here:
+
+- [Start here](release_bundle/2026-05_newsletter_cost_optimization/START_HERE.md) -- thin pointer to the customer companion.
+- [Customer companion](release_bundle/2026-05_newsletter_cost_optimization/CUSTOMER_COMPANION.md) -- canonical landing page with developer and admin guidance for cost-aware Copilot usage.
+- [System release notes](release_bundle/2026-05_newsletter_cost_optimization/NEWSLETTER_SYSTEM_RELEASE_NOTES.md) -- technical deep dive with exact before/after token counts, code links, and an illustrative cost translation.
+- [Admin and FinOps guide](release_bundle/2026-05_newsletter_cost_optimization/ADMIN_FINOPS_GUIDE.md) -- budgets, reporting, governance, attribution, baseline, and showback guidance.
+- [Developer guide](release_bundle/2026-05_newsletter_cost_optimization/DEVELOPER_GUIDE.md) -- cost-aware agentic workflows with public-safe worked examples.
+- [Product feature quick hits](release_bundle/2026-05_newsletter_cost_optimization/PRODUCT_FEATURE_QUICK_HITS.md) -- first-party source inventory for billing, budgets, observability, routing, and token-mechanics references.
+
+Public wording intentionally uses rounded aggregate/proxy metrics and caveats.
+Exact retained-run logs, private paths, raw token tables, and internal source
+notes stay in the private source repository.
+
+## Lower-Token Newsletter Workflow
+
+The most reliable way to lower token pressure is to reduce repeated work while
+keeping validation in the route. Use the admitted prompt-rendered production path
+as the oracle for its pinned range, then use the diagnostic harness only when you
+need phase-level repair.
+
+```bash
+# 1. Prepare the cycle and clear stale intermediates.
+bash tools/prepare_newsletter_cycle.sh 2026-02-14 2026-04-16 --no-reuse
+
+# 2. Run the prompt-rendered production oracle for the admitted April range.
+make newsletter-gen START=2026-02-14 END=2026-04-16 MODE=production
+
+# 3. Validate the generated newsletter.
+make validate-newsletter FILE=output/2026-04_april_newsletter.md
+bash tools/validate_pipeline_strict.sh 2026-02-14 2026-04-16 --require-fresh --production-artifacts
+```
+
+`MODE=production` is intentionally pinned in
+[render_product_run_prompt.sh](tools/render_product_run_prompt.sh). For other
+date ranges, use the same workflow pattern, but do not swap arbitrary dates into
+`MODE=production` unless the helper has been extended and validated for that
+range.
+
+Optimization order:
+
+1. Bind the date range, source set, and acceptance criteria before generation.
+2. Reuse accepted artifacts only when identity, freshness, and scope are clear.
+3. Compact expensive curation inputs only after preserving required source
+  classes and fallback.
+4. Suppress broad search or tools only when the relevant files and artifacts are
+  already known.
+5. Promote model, reasoning, or output-shape changes only after route-level
+  validation passes.
+
+The May bundle explains the measured workflow signal and the claim boundaries in
+more detail. It does not claim Copilot billing savings, durable savings, model
+superiority, or universal percentages.
+
 ## System Overview
 
 | Component | Count | Key Files |
@@ -150,8 +216,17 @@ make newsletter START= END=   # Full pipeline orchestration
 make help                      # Show all 62 targets
 ```
 
+Newsletter-specific validation can also be run directly:
+
+```bash
+bash .github/skills/newsletter-validation/scripts/validate_newsletter.sh output/YYYY-MM_month_newsletter.md
+bash tools/validate_pipeline_strict.sh START_DATE END_DATE --require-fresh --production-artifacts
+bash tools/score-v2-rubric.sh output/YYYY-MM_month_newsletter.md
+```
+
 ## Documentation
 
 - [Public repo guide](reference/public_repo_guide.md) -- publication boundary and review checklist
+- [May cost optimization bundle](release_bundle/2026-05_newsletter_cost_optimization/CUSTOMER_COMPANION.md) -- canonical shipped-newsletter companion, persona paths, playbooks, examples, and system release notes
 - [April launch bundle](release_bundle/2026-04_newsletter_launch/START_HERE.md) -- production command and validation gates
 - [February public launch bundle](release_bundle/2026-02_newsletter_launch/public/START_HERE.md) -- public case study and runnable example

docs/architecture.md

@@ -33,7 +33,30 @@ flowchart LR
 - Phase prompts: `.github/prompts/*.prompt.md`
 - Fresh-cycle prep: `tools/prepare_newsletter_cycle.sh`
 - Strict validation: `tools/validate_pipeline_strict.sh`
+- Production prompt rendering: `tools/render_product_run_prompt.sh`
+- Newsletter validation: `.github/skills/newsletter-validation/scripts/validate_newsletter.sh`
+- Public snapshot boundary: `tools/public_snapshot_allowlist.txt` and `tools/public_snapshot_prune.txt`
 - Deterministic event sources:
   - `kb/EVENT_SOURCES.yaml`
   - `tools/extract_event_sources.py`
 - Output sample: `output/2026-02_february_newsletter.md`
+
+## Cost-Aware Architecture
+
+The May 2026 update makes cost behavior part of the workflow architecture:
+
+```mermaid
+flowchart LR
+  A[Accepted source sets] --> B[Artifact reuse]
+  B --> C[Compact Phase 3 working set]
+  C --> D[Readiness checks]
+  D --> E[Tool-bounded synthesis]
+  D --> F[Fallback to fuller context]
+  E --> G[Newsletter validation]
+  F --> G
+  G --> H[Claim boundaries]
+```
+
+The important architecture rule is that optimization and quality are coupled. A route is not accepted because it uses fewer tokens; it is accepted only when the final newsletter passes validation and the evidence is labeled correctly.
+
+For the concrete file map, see the [May system release notes](https://github.com/briancl2/CustomerNewsletter/blob/main/release_bundle/2026-05_newsletter_cost_optimization/NEWSLETTER_SYSTEM_RELEASE_NOTES.md).

docs/how-it-works.md

@@ -6,6 +6,8 @@ way.
 
 If you want to run it, start with:
 - [Start here (Feb 2026)](launch/2026-02/start-here.md)
+- [May 2026 cost optimization companion](https://github.com/briancl2/CustomerNewsletter/blob/main/release_bundle/2026-05_newsletter_cost_optimization/CUSTOMER_COMPANION.md)
+- [May 2026 system release notes](https://github.com/briancl2/CustomerNewsletter/blob/main/release_bundle/2026-05_newsletter_cost_optimization/NEWSLETTER_SYSTEM_RELEASE_NOTES.md)
 
 ## Pipeline Phases
 
@@ -31,6 +33,23 @@ Examples:
 - `workspace/newsletter_phase3_curated_sections_*.md`
 - `output/YYYY-MM_month_newsletter.md`
 
+## Cost-Aware Run Pattern
+
+The current production-like route starts with a clean cycle, runs the admitted prompt-rendered production command for its pinned range, and validates the output before any cost or quality claim is made.
+
+```bash
+bash tools/prepare_newsletter_cycle.sh 2026-02-14 2026-04-16 --no-reuse
+make newsletter-gen START=2026-02-14 END=2026-04-16 MODE=production
+make validate-newsletter FILE=output/2026-04_april_newsletter.md
+bash tools/validate_pipeline_strict.sh 2026-02-14 2026-04-16 --require-fresh --production-artifacts
+```
+
+`MODE=production` is pinned to the April 2026 range by the prompt renderer. For another date range, reuse the workflow pattern and validation gates, but first extend and validate the admitted prompt-rendered mode for that range.
+
+The token-efficient path is about reducing repeated work, not just shortening prompts. The system now emphasizes accepted source sets, artifact reuse, compact Phase 3 curation inputs, readiness checks, and fallback to fuller context when quality is at risk.
+
+Use `tools/run_newsletter_orchestrated.sh` for phase-local diagnosis when the prompt-rendered route needs repair. Treat it as diagnostic unless the release notes for a given run say otherwise.
+
 ## Self-Learning Loop
 
 Corrections are encoded into skills and references, then validated by scoring and rule
@@ -45,3 +64,5 @@ Finding -> Root cause -> Skill/rule update -> Regenerate -> Validate -> Record l
 ## Trust Disk, Not Self-Reports
 
 The system relies on file-based proof and deterministic checks rather than agent claims.
+
+For cost-related claims, the proof must also say what it does not prove. The May bundle labels workflow movement as aggregate/proxy evidence, not Copilot billing proof, durable savings, model superiority, or fleet readiness.

docs/index.md

@@ -7,12 +7,33 @@ A public, reusable system for drafting enterprise-focused Copilot newsletters.
 If you only read one page, start here:
 - [Start here (Feb 2026)](launch/2026-02/start-here.md)
 
+For the current cost-aware workflow release:
+- [May 2026 cost optimization companion](https://github.com/briancl2/CustomerNewsletter/blob/main/release_bundle/2026-05_newsletter_cost_optimization/CUSTOMER_COMPANION.md) (canonical landing page from the shipped newsletter)
+- [May 2026 system release notes](https://github.com/briancl2/CustomerNewsletter/blob/main/release_bundle/2026-05_newsletter_cost_optimization/NEWSLETTER_SYSTEM_RELEASE_NOTES.md)
+- [May 2026 product feature quick hits](https://github.com/briancl2/CustomerNewsletter/blob/main/release_bundle/2026-05_newsletter_cost_optimization/PRODUCT_FEATURE_QUICK_HITS.md)
+
+The companion's `START HERE` section routes to the start-here copy, FinOps playbook, worked examples, admin guide, developer guide, and source references.
+
 Then, if you want the backstory:
 - [Short case study](launch/2026-02/case-study.md)
 - [Timeline](launch/2026-02/timeline.md)
 
 Want to see a real shipped example?
 - [Published February issue (Discussion #18)](https://github.com/briancl2/CustomerNewsletter/discussions/18)
+- [Published May issue (Discussion #21)](https://github.com/briancl2/CustomerNewsletter/discussions/21)
+
+## Current Release Focus
+
+The May 2026 release bundle explains how the newsletter generation system was updated to reduce repeated agent work while keeping validation in the route. It covers:
+
+- how to generate a newsletter with fewer wasted tokens
+- how to apply the same workflow patterns to other agentic systems
+- what changed across the source-pruning, artifact-reuse, compact-working-set, validation, and publication surfaces
+- which Copilot billing, budget, reporting, model-routing, and provider token-mechanics sources support the guidance
+- how FinOps teams can reason about baselines, budget layers, showback, and savings-claim discipline
+- worked examples for content generation, docs updates, debugging, budget-block triage, and custom agent workflows
+
+The bundle uses rounded aggregate/proxy workflow metrics with explicit non-billing caveats. Private run logs, exact token tables, retained evidence paths, and internal source notes are not published.
 
 ## Try It
 
@@ -49,3 +70,4 @@ copilot --agent customer_newsletter --model claude-opus-4.7 -i
 - [How it works](how-it-works.md)
 - [Architecture](architecture.md)
 - [Feb 2026 system report](reports/newsletter_system_report_2026-02.md)
+- [May 2026 cost optimization bundle](https://github.com/briancl2/CustomerNewsletter/tree/main/release_bundle/2026-05_newsletter_cost_optimization)

mkdocs.yml

@@ -22,6 +22,10 @@ nav:
       - Start Here: launch/2026-02/start-here.md
       - Case Study: launch/2026-02/case-study.md
       - Timeline: launch/2026-02/timeline.md
+  - May 2026 Cost Bundle:
+      - Customer Companion: https://github.com/briancl2/CustomerNewsletter/blob/main/release_bundle/2026-05_newsletter_cost_optimization/CUSTOMER_COMPANION.md
+      - System Release Notes: https://github.com/briancl2/CustomerNewsletter/blob/main/release_bundle/2026-05_newsletter_cost_optimization/NEWSLETTER_SYSTEM_RELEASE_NOTES.md
+      - Product Quick Hits: https://github.com/briancl2/CustomerNewsletter/blob/main/release_bundle/2026-05_newsletter_cost_optimization/PRODUCT_FEATURE_QUICK_HITS.md
   - How It Works: how-it-works.md
   - Architecture: architecture.md
   - Reports: