@laitszkin/apollo-toolkit 2.12.3 → 2.12.4

package/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to this repository are documented in this file.
 
 ## [Unreleased]
 
+## [v2.12.4] - 2026-04-01
+
+### Added
+- Add a bundled macOS `PDFKit` extraction helper for `weekly-financial-event-report` so marked-event PDFs can still be parsed locally when the usual PDF tooling is unavailable.
+
+### Changed
+- Expand `weekly-financial-event-report` to prefer the `pdf` skill for extraction, fall back to the local PDFKit helper on macOS, and call `document-vision-reader` when visual highlights are not recoverable from extracted text alone.
+- Rework `align-project-documents` around category-based, newcomer-friendly documentation selection with a reusable template grounded in Diataxis and common open source doc types.
+- Tighten `commit-and-push` and `version-release` so clean-worktree submit/release requests must inspect existing local and remote state instead of fabricating a new submission result.
+- Strengthen `production-sim-debug` to record the active artifact root immediately and check startup admission signals before concluding a run had no opportunities.
+
 ## [v2.12.3] - 2026-03-30
 
 ### Changed

package/align-project-documents/SKILL.md

@@ -16,12 +16,12 @@ description: Read and understand a software project, then generate or align proj
 
 - Evidence: Treat source code, configuration, scripts, and tests as the source of truth.
 - Execution: Discover project facts before choosing generate mode or align mode.
-- Quality: Keep every non-trivial claim traceable and remove stale documentation instead of appending around it.
-- Output: Write concise, operator-friendly docs with runnable commands and clear section structure.
+- Quality: Keep every non-trivial claim traceable, choose document categories based on actual content, and remove stale documentation instead of appending around it.
+- Output: Write newcomer-friendly docs with descriptive headings, runnable commands, and clear reader guidance.
 
 ## Goal
 
-Produce accurate, code-grounded project documentation. Prefer evidence from source code, configs, scripts, and tests over assumptions.
+Produce accurate, code-grounded project documentation that remains readable for people who do not yet understand the project, its domain, or the development workflow. Prefer evidence from source code, configs, scripts, and tests over assumptions.
 
 ## Workflow
 
@@ -31,24 +31,58 @@ Produce accurate, code-grounded project documentation. Prefer evidence from sour
 - Inspect main runtime paths (API/server, worker, frontend, CLI, jobs) and dependency boundaries.
 - Build a factual map: startup commands, environment variables, request/data flow, major modules, external integrations, and observability points.
 - Record concrete evidence with file paths for every important claim.
-
-### 2) Decide documentation mode
+- Identify likely readers and their knowledge gaps: new developer, operator, support teammate, product stakeholder, or mixed audience.
+- Identify the actual reader tasks: understand the project, run locally, configure credentials, operate a workflow, debug failures, or change code safely.
+
+### 2) Classify documentation by content, not by fixed headings
+
+- Start from the repository's real content and the readers' jobs to be done.
+- Choose only the categories that are supported by evidence and useful to the target audience.
+- Use open source documentation conventions as the classification baseline instead of inventing project-local categories first.
+- Prefer the Diataxis content families for content classification: tutorial, how-to, reference, and explanation.
+- Map those content families onto common open source document types when appropriate: `README`, `CONTRIBUTING`, `SECURITY`, `CODE_OF_CONDUCT`, troubleshooting guides, glossary, and release/change documents.
+- Prefer descriptive, task-led headings such as `本地啟動 API 服務`, `設定 GitHub OAuth 憑證`, or `匯入任務卡住時如何排查`.
+- Do not force a fixed chapter list when the project does not need it.
+- Use `references/templates/category-based-project-docs-template.md` as the primary selection guide.
+
+Useful content categories include:
+
+- README or docs index for orientation
+- tutorial or getting-started guide for first success
+- how-to or runbook guides for real tasks
+- reference docs for configuration, commands, endpoints, and limits
+- explanation docs for architecture, concepts, and tradeoffs
+- CONTRIBUTING for contribution workflow
+- SECURITY for vulnerability reporting and support policy
+- CODE_OF_CONDUCT for community expectations
+- glossary, FAQ, decisions, or release notes when repository evidence shows they are needed
+
+### 3) Decide documentation mode
 
 - **Generate mode**: no usable docs exist, or user asks to create docs from scratch.
 - **Align mode**: existing docs exist and must be checked against implementation.
 
-### 3) Generate mode output
+### 4) Generate mode output
+
+Create or update a minimal document set chosen from the content categories above. Do not require every project to have the same headings or files.
+
+At minimum, ensure the final output answers the questions that matter for the repository's real readers:
 
-Create or update documentation with at least these sections:
+1. What is this project for?
+2. Who usually needs this document?
+3. How do I complete the most common task safely?
+4. What must I prepare before I start?
+5. What result should I expect if things are working?
+6. What usually goes wrong and how do I verify it?
+7. Where in the repository is the source of truth?
 
-1. Project Overview
-2. Quick Start / Local Run
-3. Usage Guide (common workflows and commands)
-4. Technical Architecture (components, boundaries, data flow)
-5. Configuration and Environment Variables
-6. Debugging Playbook (symptom -> checks -> likely root cause -> fix path)
-7. Testing and Validation
-8. Deployment or Runtime Notes (if applicable)
+Recommended output pattern:
+
+- A short root `README.md` or equivalent entry document for orientation.
+- One or more focused documents grouped by standard documentation type.
+- Optional runbooks for task-heavy or failure-heavy workflows.
+- Optional glossary/FAQ material only when the project actually contains domain complexity or repeated team confusion.
+- Separate contributor or community-governance docs only when the repository exposes those collaboration workflows.
 
 Writing rules:
 
@@ -56,8 +90,12 @@ Writing rules:
 - Use concrete commands and paths from the repository.
 - Keep examples executable when possible.
 - Call out unknowns explicitly instead of guessing.
+- Explain why a file, service, command, or environment matters before telling the reader to use it.
+- Assume the reader may not understand local jargon, deployment assumptions, or the project's business terms.
+- Prefer task-oriented section titles over generic labels.
+- Keep different documentation intents separate: tutorials teach, how-to guides solve tasks, reference catalogs facts, and explanation pages provide understanding.
 
-### 4) Align mode output
+### 5) Align mode output
 
 When docs already exist:
 
@@ -70,6 +108,7 @@ When docs already exist:
    - **Ambiguous**
 4. Update docs to match real behavior.
 5. Add a short "Documentation Delta" summary listing major corrections.
+6. Rewrite headings that are too generic or template-like so they reflect the real task or concept being documented.
 
 Alignment checklist:
 
@@ -79,6 +118,18 @@ Alignment checklist:
 - Config keys and env vars match code usage.
 - Debug instructions reference real logs, metrics, and breakpoints.
 - Test commands and expected outputs are current.
+- Headings match actual content categories instead of forcing one universal structure.
+- Newcomers can infer what each document is for before reading the full content.
+- Document placement follows recognizable open source conventions whenever the repository scope justifies them.
+
+### 6) Newcomer-readability rules
+
+- Start each document by making the reader's situation explicit: who this is for, what they are trying to do, and when they should use this document.
+- When describing a task, include prerequisites, exact steps, expected signals, and common failure recovery.
+- When describing architecture, explain responsibilities and boundaries in plain language before diving into paths or modules.
+- When describing configuration or credentials, explain why each key or service exists and what breaks if it is missing.
+- When describing debugging, structure content around observable symptoms and verification paths, not abstract subsystem names.
+- If the repository contains specialist domain language, add a glossary or inline definitions instead of assuming prior knowledge.
 
 ## Quality Gate (must pass before finishing)
 
@@ -86,9 +137,23 @@ Alignment checklist:
 - Ensure usage and debug steps are reproducible from current code.
 - Ensure architecture description reflects actual module boundaries.
 - Ensure outdated statements are removed, not only appended.
+- Ensure document categories and headings are chosen because they fit the content, not because the template listed them.
+- Ensure a newcomer can identify the correct next step from the document without already knowing the codebase.
+- Ensure the chosen document types align with common open source practice so contributors can find information where they expect it.
 
 ## Output Style
 
-- Write concise, operator-friendly documentation.
-- Use headings, short bullets, and runnable command snippets.
+- Write concise but high-context documentation for humans, not placeholder-driven template output.
+- Use headings, short bullets, tables, and runnable command snippets when they improve scanning.
 - Prefer direct language and avoid speculative wording.
+- Make headings descriptive enough that a reader can skim the table of contents and know which page or section to open.
+
+## Reference Template
+
+- `references/templates/category-based-project-docs-template.md`: category-based template and reusable section blocks for newcomer-friendly project documentation.
+
+## External Documentation Basis
+
+- Diataxis: use the tutorial / how-to / reference / explanation model as the primary content classification.
+- The Good Docs Project: use common open source template types such as README, quickstart, tutorial, how-to, troubleshooting, glossary, and style-oriented guidance as practical packaging patterns.
+- GitHub open source guidance: treat `README`, `CONTRIBUTING`, license, code of conduct, and security policy as common repository-level documents when the project has contributor-facing community workflows.

package/align-project-documents/references/templates/category-based-project-docs-template.md

@@ -0,0 +1,170 @@
+# Category-Based Project Documentation Template
+
+Use this template as a selection guide, not a mandatory outline. Start by classifying the repository's real content and the readers' likely questions, then choose only the document categories and section blocks that are actually supported by evidence.
+
+Base the classification on common open source documentation practice:
+
+- Use the Diataxis content families when deciding what kind of content you are writing: tutorial, how-to, reference, and explanation.
+- Use common open source repository documents when deciding where the content should live: `README`, `CONTRIBUTING`, `SECURITY`, `CODE_OF_CONDUCT`, troubleshooting guides, glossary, and release notes when applicable.
+- Use The Good Docs Project templates as a practical guide for selecting content types that teams repeatedly need in real projects.
+
+## 1. Start With Reader And Content Classification
+
+Before writing, identify:
+
+| Classification | Questions to answer | Example answers |
+| --- | --- | --- |
+| Primary readers | Who needs this document first? | New developer, operator, support teammate, PM, founder |
+| Reader background | What might they not know yet? | No repo context, no local setup experience, no domain knowledge |
+| Main job to be done | What is the reader trying to accomplish? | Run locally, change a feature, deploy, debug an incident |
+| Evidence sources | Which files prove the behavior? | `README.md`, `package.json`, `src/server.ts`, `.github/workflows/deploy.yml` |
+| Documentation risk | What would go wrong if this is undocumented? | Broken onboarding, misconfigured secrets, incorrect production operation |
+
+Write the document around the real questions above. Do not force a category or section when the repository does not support it.
+
+## 2. Choose The Right Document Categories
+
+Select one or more categories below. Keep the titles content-led and specific. Prefer titles such as `本地啟動後端服務`, `設定 Stripe 測試金鑰`, or `訂單同步失敗時如何排查`, instead of generic headings that hide the real task.
+
+| Open source documentation type | Diataxis family | Use when the repository contains... | Main reader need | Suggested output path |
+| --- | --- | --- | --- |
+| README / docs index | Mixed entrypoint | Clear project purpose, user value, repo scope, key links | "What is this project and where do I start?" | `README.md`, `docs/README.md` |
+| Tutorial / getting started | Tutorial | A first-run path that teaches by doing | "Help me complete my first successful run." | `docs/getting-started.md`, `docs/tutorials/*.md` |
+| How-to / runbook / operations guide | How-to | Repeated workflows, CLI commands, dashboards, jobs, support actions | "How do I perform this real task?" | `docs/how-to/*.md`, `docs/runbooks/*.md`, `docs/operations.md` |
+| Reference / configuration catalog | Reference | Env vars, config files, commands, endpoints, state tables, limits | "What options, inputs, or values exist?" | `docs/configuration.md`, `docs/reference/*.md` |
+| Explanation / architecture / concepts | Explanation | Module boundaries, data flow, ownership, state transitions, tradeoffs | "How is this built and why is it shaped this way?" | `docs/architecture.md`, `docs/concepts/*.md` |
+| Troubleshooting | How-to + reference | Known symptoms, causes, checks, recovery actions | "What should I check when it breaks?" | `docs/troubleshooting.md`, `docs/runbooks/*.md` |
+| CONTRIBUTING | How-to + explanation | Contribution flow, local validation, review expectations | "How do I contribute safely?" | `CONTRIBUTING.md`, `docs/developer-guide.md` |
+| SECURITY | How-to + reference | Vulnerability reporting process, supported versions, security boundaries | "How should I report a security issue?" | `SECURITY.md` |
+| CODE_OF_CONDUCT | Community governance | Community expectations and reporting path | "How does this project expect people to behave?" | `CODE_OF_CONDUCT.md` |
+| Glossary / terminology | Reference | Business rules, lifecycle states, project vocabulary, permissions | "What do these terms mean?" | `docs/glossary.md`, `docs/terminology.md` |
+| FAQ / decisions / release notes | Explanation + reference | Repeated questions, key tradeoffs, notable changes | "Why was this choice made?" / "What changed?" | `docs/faq.md`, `docs/decisions/*.md`, `CHANGELOG.md` |
+
+### Selection Rules
+
+- Start by asking which Diataxis family the content belongs to.
+- Then choose the most conventional open source document type that readers would expect to find.
+- Do not merge tutorial, how-to, reference, and explanation into one page unless the repository is genuinely small enough that separation would hurt readability.
+- Keep community-governance documents such as `CONTRIBUTING`, `SECURITY`, and `CODE_OF_CONDUCT` separate from product usage docs.
+- When a document mixes content types, decide which type is primary and move the rest behind links.
+
+## 3. Section Blocks You Can Reuse Inside Any Document
+
+Use only the blocks that help the target reader. Rename each heading to match the specific content.
+
+### A. Reader Context Block
+
+Use when the reader may not understand the project or task yet.
+
+- Who should read this:
+- What they are probably trying to do:
+- What they need to know first:
+- What success looks like after reading:
+
+### B. Before You Start Block
+
+Use for setup, operations, deployments, or debugging.
+
+- Required tools or accounts:
+- Required permissions or credentials:
+- Files, services, or environments involved:
+- Safe test or sandbox alternatives:
+
+### C. Exact Steps Block
+
+Use for any task-oriented content.
+
+1. State the action in plain language.
+2. Give the exact command, UI path, or file path.
+3. Explain what result should appear.
+4. Explain what to do if the result does not appear.
+
+### D. Expected Signals Block
+
+Use when readers need to confirm they are on the right path.
+
+- Success logs, UI states, API responses, artifacts, or screenshots:
+- Expected side effects:
+- How long the step usually takes:
+
+### E. Failure And Recovery Block
+
+Use when the workflow can fail or confuse newcomers.
+
+- Common mistake:
+- Symptom:
+- Likely cause:
+- How to verify:
+- How to fix:
+
+### F. Code Navigation Block
+
+Use for architecture or developer-facing docs.
+
+- Entry point:
+- Main modules and responsibilities:
+- Important data models:
+- External integration touchpoints:
+- Highest-risk files to review before editing:
+
+### G. Decision And Limitation Block
+
+Use when the code or operations include tradeoffs.
+
+- Current limitation:
+- Why it exists:
+- When it matters:
+- Safe workaround:
+- Evidence:
+
+## 4. Newcomer-Friendly Writing Rules
+
+Every non-trivial document should help a reader who does not yet know the project. Prefer explaining:
+
+- what this part of the system is for
+- why the reader would need it
+- what they must prepare beforehand
+- what exact action they should take
+- what result they should expect
+- what usually goes wrong
+- where in the repository the truth lives
+
+Avoid:
+
+- headings that only repeat template words without conveying meaning
+- assuming the reader already knows internal jargon
+- mentioning files, services, or commands without saying why they matter
+- mixing future plans with current behavior
+
+## 5. Evidence Checklist
+
+Before finishing, confirm:
+
+- every important instruction maps to code, config, scripts, tests, or current deployment files
+- every command is current and runnable, or explicitly marked as needing manual confirmation
+- each document category exists because the repository actually needs it
+- each heading is descriptive of the real content, not just copied from a template
+- unknowns are labeled clearly instead of guessed
+
+## 6. Example Of Category Selection
+
+Example classification:
+
+- Readers: new developer and part-time operator
+- Main needs: local startup, environment configuration, order sync debugging
+- Repository evidence: API server, worker process, queue config, deploy workflow, sync failure logs
+
+Reasonable outputs:
+
+- `README.md`: project overview and links
+- `docs/getting-started.md`: tutorial-style first successful run
+- `docs/configuration.md`: reference-style env vars and third-party credentials
+- `docs/architecture.md`: explanation of API, worker, queue, and database boundaries
+- `docs/runbooks/order-sync-failures.md`: how-to troubleshooting for order sync issues
+- `CONTRIBUTING.md`: contribution flow, local checks, and review expectations if external contributors are expected
+
+Not needed unless evidence supports them:
+
+- `docs/glossary.md`
+- `docs/faq.md`
+- separate feature catalog for every route/page

package/commit-and-push/SKILL.md

@@ -15,7 +15,7 @@ description: "Guide the agent to submit local changes with commit and push only
 ## Standards
 
 - Evidence: Inspect git state and classify the change set before deciding which quality gates apply, then compare the actual pending diff against root `CHANGELOG.md` `Unreleased` before committing.
-- Execution: Run the required quality-gate skills when applicable, and treat every conditional gate whose scenario is met as blocking before submission; hand the repository to `submission-readiness-check` for changelog/docs/plan finalization, preserve staging intent, honor any explicit user-specified target branch, then commit and push without release steps; run dependent git mutations sequentially and verify the remote branch actually contains the new local `HEAD` before reporting success.
+- Execution: Run the required quality-gate skills when applicable, and treat every conditional gate whose scenario is met as blocking before submission; hand the repository to `submission-readiness-check` for changelog/docs/plan finalization, preserve staging intent, honor any explicit user-specified target branch, and when the worktree is already clean inspect local `HEAD`, upstream state, and the most recent relevant commit before deciding the request is a no-op; then commit and push without release steps; run dependent git mutations sequentially and verify the remote branch actually contains the new local `HEAD` before reporting success.
 - Quality: Re-run relevant validation for runtime changes, preserve unrelated local work safely when branch switching or post-push local sync is required, and do not bypass blocking readiness findings such as missing/stale `Unreleased` bullets or unsynchronized project docs.
 - Output: Produce a concise Conventional Commit, push it to the intended branch, and report any temporary stash/restore or local branch sync that was required.
 
@@ -36,6 +36,7 @@ Load only when needed:
    - Run `git status -sb`, `git diff --stat`, and `git diff --cached --stat`.
    - Check staged files with `git diff --cached --name-only`.
    - Inventory repository planning artifacts and project docs, not only staged files, to detect repo specs and non-standard documentation layouts.
+   - If the worktree is already clean, inspect `git log -1 --stat`, local `HEAD`, and the configured upstream state before concluding there is nothing to submit; use that evidence to determine whether the requested work was already committed and pushed, committed but not pushed, or never landed.
 2. Classify changes
    - `code-affecting`: runtime code, tests, build scripts, CI logic, or behavior-changing config.
    - `docs-only`: content updates only (for example README, docs, comments).
@@ -78,6 +79,7 @@ Load only when needed:
 - Never skip `review-change-set` for code-affecting changes, and do not continue past review while confirmed findings remain unresolved.
 - Never downgrade `discover-edge-cases` or `harden-app-security` to optional follow-up when the change risk says they apply.
 - Never claim the repository is ready to commit while root `CHANGELOG.md` `Unreleased` is missing the current change or still describes superseded work.
+- Never fabricate a commit/push result when the worktree is already clean; either identify the exact existing commit/upstream state that satisfies the user's request or say that no matching new submission exists.
 - If release/version/tag work is requested, use `version-release` instead.
 - If a new branch is required, follow `references/branch-naming.md`.
 - A pushed implementation can still leave an active spec set behind; commit completion and spec archival are separate decisions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laitszkin/apollo-toolkit",
-  "version": "2.12.3",
+  "version": "2.12.4",
   "description": "Apollo Toolkit npm installer for managed skill copying across Codex, OpenClaw, and Trae.",
   "license": "MIT",
   "author": "LaiTszKin",

package/production-sim-debug/SKILL.md

@@ -41,6 +41,7 @@ Use this skill to debug simulation workflows where the repository exposes a prod
 
 - Use the same production/local simulation script the repository already treats as canonical.
 - Prefer a bounded run window with a stable run name and output directory.
+- As soon as the harness prints the active run name or output directory, record it and treat that path as the canonical artifact root for the rest of the investigation.
 - Before launch, read the script or wrapper that enforces the run duration and confirm the real control surface, such as the exact env var name, CLI flag, shutdown helper, and artifact path conventions.
 - Do not assume a generic `RUNTIME_SECS`-style variable is wired correctly; verify the actual variable names and stop path from code or scripts first.
 - Save and inspect the exact artifacts produced by that run:
@@ -56,6 +57,7 @@ Use this skill to debug simulation workflows where the repository exposes a prod
 
 - Confirm that you are reading the correct database and log files for the active run.
 - Verify that the event tables you expect are actually the ones written by the runtime.
+- When the run appears "too clean" or fully zeroed, inspect startup selection counters first, such as candidate pool size, listener/tracked-position counts, or the repository's equivalent admission signals, before concluding there were simply no opportunities.
 - Check whether missing results come from:
   - no candidate selection
   - no worker completion

package/version-release/SKILL.md

@@ -15,7 +15,7 @@ description: "Guide the agent to prepare and publish a versioned release (versio
 ## Standards
 
 - Evidence: Inspect the active change set, current version files, existing tag format, existing remote tags/releases, and root `CHANGELOG.md` `Unreleased` content before touching version files, tags, or release metadata.
-- Execution: Use this workflow only for explicit release intent, run the required quality gates when applicable, and treat every conditional gate whose scenario is met as blocking before versioning or publication; hand the repository to `submission-readiness-check` before versioning work, then cut the release directly from `CHANGELOG.md` `Unreleased`, update versions and docs, commit, tag, push, and publish the GitHub release; run git mutations sequentially and verify both the branch tip and release tag exist remotely before publishing the GitHub release.
+- Execution: Use this workflow only for explicit release intent, run the required quality gates when applicable, and treat every conditional gate whose scenario is met as blocking before versioning or publication; hand the repository to `submission-readiness-check` before versioning work, and if the worktree is already clean inspect the current version, local/remote tag state, and existing GitHub release state before deciding whether the request is already satisfied; then cut the release directly from `CHANGELOG.md` `Unreleased`, update versions and docs, commit, tag, push, and publish the GitHub release with actual release tooling rather than PR-surrogate directives; run git mutations sequentially and verify both the branch tip and release tag exist remotely before publishing the GitHub release.
 - Quality: Never guess versions, align user-facing docs with actual code, do not bypass readiness blockers from `submission-readiness-check`, do not reconstruct release notes from `git diff` when curated changelog content already exists, and do not report release success until the commit, tag, and GitHub release all exist for the same version.
 - Output: Produce a versioned release commit and tag, publish a matching GitHub release, and keep changelog plus relevant repository documentation synchronized.
 
@@ -67,6 +67,7 @@ Load only when needed:
    - Read existing version files (for example `project.toml`, `package.json`, or repo-specific version files).
    - Infer existing tag format (`vX.Y.Z` or `X.Y.Z`) from repository tags.
    - Inspect existing local and remote tags plus any existing GitHub Release for the target version before creating new release metadata, so duplicate or conflicting releases are caught early.
+   - If the requested version tag and matching published GitHub release already exist and point at the intended commit, report that the release is already complete instead of creating duplicate metadata.
    - If the user provides the target version, use it directly.
    - If it is missing, ask the user for the target version or semver bump type.
    - Provide recommendations only when explicitly requested.
@@ -96,6 +97,7 @@ Load only when needed:
    - Use the release notes from the new `CHANGELOG.md` entry unless the repository has a stronger established release-note source.
    - If the repository has publish automation triggered by `release.published`, ensure the GitHub release is actually published rather than left as a draft.
    - Prefer `gh release create <tag>` or the repository's existing release tool when available.
+   - Do not use PR-opening tools, PR directives, or placeholder URLs as a substitute for actual release publication.
    - Confirm the GitHub release URL and any triggered publish workflow status in the final report.
    - Never stop after the release commit or tag alone; creating the matching GitHub release is part of done criteria unless the user explicitly says to skip release publication.
 
@@ -106,5 +108,6 @@ Load only when needed:
 - Never skip `review-change-set` for code-affecting releases, and do not continue to versioning work while confirmed review findings remain unresolved.
 - Never downgrade `discover-edge-cases` or `harden-app-security` to optional follow-up when the release risk says they apply.
 - Never claim a release is complete without checking the actual release version, creating the matching tag, and publishing the matching GitHub release.
+- Never treat a PR creation step, release-page URL guess, or tag-only push as evidence that the GitHub release exists.
 - If tests are required by repository conventions, run them before commit.
 - If a new branch is required, follow `references/branch-naming.md`.

package/weekly-financial-event-report/SKILL.md

@@ -7,15 +7,15 @@ description: Read a user-specified PDF that marks the week's key financial event
 
 ## Dependencies
 
-- Required: `pdf` to read the source PDF and render the final report.
-- Conditional: none.
+- Required: `pdf` to render the final report.
+- Conditional: `document-vision-reader` when the source PDF's highlighted markers are visible in layout but not recoverable from machine-readable text alone.
 - Optional: none.
-- Fallback: If `pdf` is unavailable, stop and report the missing dependency instead of improvising another PDF workflow.
+- Fallback: If source-PDF extraction through `pdf` is unavailable or fails on macOS, use the bundled `scripts/extract_pdf_text_pdfkit.swift` helper before giving up; only stop when neither `pdf` nor the local PDFKit fallback can recover the marked events, or when final PDF rendering itself cannot be completed.
 
 ## Standards
 
 - Evidence: Research only events explicitly marked in the source PDF plus clearly material breaking developments, and verify claims with current authoritative sources.
-- Execution: Read the PDF first, lock the research window, research each marked event, then hand the final briefing to `pdf` for rendering and QA with deterministic table-safe layout rules when needed.
+- Execution: Read the PDF first, prefer `pdf` for extraction but fall back to the bundled macOS PDFKit extractor when local PDF tooling is missing, lock the research window, research each marked event, then hand the final briefing to `pdf` for rendering and QA with deterministic table-safe layout rules when needed.
 - Quality: Keep the report concise, Chinese-compatible, explicit about source-versus-breaking events, conflicts, uncertainty, PDF font safety, and long-text table legibility.
 - Output: Save only the final standardized PDF under the month folder using the financial-event-report naming scheme.
 
@@ -66,14 +66,22 @@ Do not guess any input that materially changes the research window or report sco
 
 ### 1) Read the source PDF and extract the marked events
 
-- Use the `pdf` skill to open and extract the source PDF.
+- Prefer the `pdf` skill to open and extract the source PDF.
+- If `pdf` extraction is unavailable or fails because the current machine lacks local PDF tooling, and the host is macOS, run:
+
+```bash
+swift scripts/extract_pdf_text_pdfkit.swift /absolute/path/to/source.pdf
+```
+
+- The bundled extractor prints page-delimited text directly from PDFKit so the agent can still build the source-event table without adding Python PDF packages ad hoc.
 - Identify the document's explicit markers, such as highlights, comments, callouts, boxed sections, bookmarks, or clearly labeled weekly key-event sections.
 - Build a source-event table before searching. For each marked event capture:
   - page number
   - event label in the source PDF
   - date or date range if present
   - short note about why the source document highlighted it
-- If the PDF does not expose machine-readable annotations, fall back to clearly visible marked sections or headings.
+- If the PDF does not expose machine-readable annotations, fall back to clearly visible marked sections or headings from the extracted page text.
+- If the page text alone is insufficient because the document uses visual highlights or layout callouts without recoverable text markers, use `document-vision-reader` on screenshots of the relevant PDF pages before deciding the events are ambiguous.
 - If the document still does not make the marked events unambiguous, stop and report the ambiguity rather than inventing events.
 
 ### 2) Lock the research window

package/weekly-financial-event-report/scripts/extract_pdf_text_pdfkit.swift

@@ -0,0 +1,71 @@
+#!/usr/bin/env swift
+
+import Foundation
+import PDFKit
+
+struct Arguments {
+    let pdfPath: String
+}
+
+enum ExtractionError: Error, CustomStringConvertible {
+    case missingPath
+    case unsupportedPlatform
+    case unreadablePDF(String)
+
+    var description: String {
+        switch self {
+        case .missingPath:
+            return "Usage: swift scripts/extract_pdf_text_pdfkit.swift /absolute/path/to/source.pdf"
+        case .unsupportedPlatform:
+            return "PDFKit extraction is only supported on macOS."
+        case .unreadablePDF(let path):
+            return "Unable to open PDF at \(path)"
+        }
+    }
+}
+
+func parseArguments() throws -> Arguments {
+    let args = Array(CommandLine.arguments.dropFirst())
+    guard let pdfPath = args.first, !pdfPath.isEmpty else {
+        throw ExtractionError.missingPath
+    }
+    return Arguments(pdfPath: pdfPath)
+}
+
+func main() throws {
+    #if !os(macOS)
+    throw ExtractionError.unsupportedPlatform
+    #else
+    let arguments = try parseArguments()
+    let pdfURL = URL(fileURLWithPath: arguments.pdfPath)
+
+    guard let document = PDFDocument(url: pdfURL) else {
+        throw ExtractionError.unreadablePDF(arguments.pdfPath)
+    }
+
+    print("PDF_PATH=\(arguments.pdfPath)")
+    print("PAGE_COUNT=\(document.pageCount)")
+
+    for pageIndex in 0..<document.pageCount {
+        guard let page = document.page(at: pageIndex) else {
+            continue
+        }
+        let text = page.string?
+            .replacingOccurrences(of: "\u{000C}", with: "\n")
+            .trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        print("=== PAGE \(pageIndex + 1) ===")
+        if text.isEmpty {
+            print("[NO_TEXT_EXTRACTED]")
+        } else {
+            print(text)
+        }
+    }
+    #endif
+}
+
+do {
+    try main()
+} catch {
+    fputs("\(error)\n", stderr)
+    exit(1)
+}