source-manifest

Source Manifest

Triggers & routing

• Trigger: source manifest, sources list, tutorial sources, url list, material list, tutorial sources.
• Use when: source-tutorial C1, it is necessary to consolidate multi-source input into a unified sources/manifest.yml, and explicitly block when the content is incomplete.
• Skip if: there is already a complete and confirmed sources/manifest.yml。
• Network: none.
• Guardrail: do not fabricate sources; when the manifest is incomplete, it should return BLOCKED instead of pretending to be complete.

Goal: collect the source candidates for source-tutorial into one explicit manifest before ingest starts.

Inputs

• GOAL.md
• DECISIONS.md

Outputs

• sources/manifest.yml

Workflow

1. Read GOAL.md and any existing DECISIONS.md notes to understand what kinds of sources the tutorial is expected to use.
2. If sources/manifest.yml does not exist, scaffold it with a minimal example.
3. Validate that each source has:
   • source_id
   • kind
   • locator
   • label
   • for kind: video, prefer transcript_locator unless the platform exposes public subtitles
4. Reject placeholder/example-only manifests.
5. Return success only when at least one real source exists.

Accepted kind

• webpage
• pdf
• markdown
• repo
• docs_site
• video

For video:

• preferred: add transcript_locator
• Bilibili may succeed from public subtitles when available
• YouTube should currently be paired with transcript_locator

Script

Quick Start

• uv run python .codex/skills/source-manifest/scripts/run.py --workspace <workspace>

All Options

• --workspace <dir> (required)
• --unit-id <U###>
• --inputs <semicolon-separated>
• --outputs <semicolon-separated>
• --checkpoint <C#>

Examples

• Scaffold or validate the manifest:
  • uv run python .codex/skills/source-manifest/scripts/run.py --workspace <workspace>

Troubleshooting

Issue: the unit keeps blocking after scaffold

Cause:

• The manifest still contains example placeholders.

Fix:

• Replace the scaffold entry with real URLs or local file paths, then rerun the unit.