Imported from r-jack-ray/naval-history-with-dr-alex (.agents/skills/naval-transcript-to-site-content/SKILL.md). Install upstream with npx skills add r-jack-ray/naval-history-with-dr-alex --skill naval-transcript-to-site-content. Copyright stays with the author.

Naval Transcript To Site Content

Use this skill inside C:\Workspaces\naval-history-with-dr-alex when converting stored transcripts into site-visible segment data.

Start

1. Read AGENTS.md and .agents/transcript-content-curator.md.
2. Before any shard edit, require an explicitly named transcript path or an exact transcript/video selected by the invoking automation. When the automation prompt defines its own atomic claim procedure, let that prompt perform the claim first. Otherwise, if no exact transcript was supplied, stop without edits; do not select from a backlog, schedule, report, manifest, or existing shard set.
3. Do not claim, complete, or reset schedule rows. An invoking automation owns any claim, lane log, private validation, completion, or reset procedure.
4. Verify required dependencies and compiled helpers only when the invoking workflow names them. If anything is missing, report the prerequisite and stop without edits; do not run npm ci, build tooling, audits, generation, or tests. The exact-shard timestamp sorter, required scoped npm run check:site-content-wording validation, and npm run sync:video-topics finalization command are the sole exceptions.
5. Read the selected src/transcripts/txt/*.txt file before editing site content. For long transcripts, map the full duration from its timestamped lines and read contiguous time-based chunks small enough to avoid tool-output truncation; do not rely on one raw full-file dump or only the opening portion.
   • Keep transcript reads antivirus-safe. Never build or run a multi-range timestamp extractor as an inline PowerShell -Command. Do not stream the full file through ForEach-Object or foreach while using regex timestamp parsing, range arrays, command-line variables, or a command-line output-encoding prelude. Do not encode, obfuscate, or move equivalent dynamic logic into an ad hoc script.
   • Read sequentially with separate, simple commands. Locate a known timestamp with rg -n --fixed-strings when useful, then read one contiguous line slice at a time with a literal path and numeric constants, for example Get-Content -LiteralPath '<transcript>' | Select-Object -Skip <line> -First <count>. If endpoint protection blocks a read, stop and report the blocked command pattern; do not retry it in another dynamic form.
6. Read .agents/skills/naval-transcript-to-site-content/references/segment-seed-schema.md before changing the selected shard.
7. Check src/derived/site-content-processing.config.json for first-pass content policy, video-type defaults, follow-up stages, and topic grouping guidance.
8. Read src/derived/topic-normalization-patterns.tsv before evaluating or changing topic arrays. Treat the catalog as read-only authored policy.
9. Read .agents/skills/humanizer/SKILL.md completely. Reserve its embedded-mode rewrite loop for the final public-wording pass below.

Site Intent

• Treat the public site as a study guide for people learning naval history, general history, and how armed forces, states, institutions, technology, and logistics work, not as creator analytics, maintainer workflow, or raw transcript inventory.
• Include substantive general history on its own merits. Ancient, medieval, early-modern, and modern political, diplomatic, economic, social, technological, industrial, aviation, military, transport, and logistical history are in scope whenever the transcript offers useful historical explanation, argument, context, or Q&A. A direct naval connection is not required.
• Treat historically framed games, simulations, and counterfactual scenarios as eligible when the discussion teaches something substantive about historical geography, strategy, operations, state capacity, economics, diplomacy, institutions, logistics, or interpretation. Distinguish game rules and scenario state from claims about actual history. Exclude technical setup, personal chatter, bare move-by-move gameplay narration, and other non-historical filler unless it develops a substantive learning point or answered question.
• Help readers find concrete ships, classes, navies, states, empires, peoples, armies, aircraft, battles, campaigns, leaders, weapons, railways, ports, places, trade routes, supply systems, policies, doctrine, logistics, institutions, acronyms, time periods, and alternate wordings.
• Use segment summaries as watch points into the source video: preview what the viewer will encounter, why that moment matters, and what naval-history, general-history, strategic, technical, or institutional question it helps answer. Explain a naval connection when one matters, but do not require one.
• Prefer granular, separate segments over a thin video-level overview when the transcript has enough distinct material.
• Keep public fields free of creator metrics, internal filenames, processing status, raw inventory language, and developer-facing labels for video time markers unless the user asks for an admin/debug view.

Curate

1. Inspect the full transcript for both subject segments and actual Q&A, regardless of source type or title. Identify useful chapters, notable points, short transcript excerpts, and every substantive transcript-visible prompt and response; do not defer Q&A wholesale to a later pass. Preserve substantive general history whether or not it connects to a navy or ship. For games, simulations, and counterfactuals, capture historically informative analysis with clear real-history-versus-scenario caveats rather than excluding the video's main subject or presenting game events as historical fact.
2. Add evidence-backed topic slugs directly to the video or segment topics arrays. Do not manually edit topics.json; the required same-run npm run sync:video-topics finalization materializes missing registry records while preserving existing manual metadata. Synchronization creates each new registry record with a blank description. Topic descriptions are optional manual metadata: never generate, infer, refresh, normalize, or clear them. Resolve active creation rules before the shard write, and treat an unresolved review or ambiguous candidate as a blocker rather than leaving a noncanonical reference for another process.
3. Add or update src/derived/video-segments/<manifest.fileStem>.json for the selected transcript. Use its stored manifest fileStem exactly: the selected transcript TXT basename must equal <fileStem>.txt, and current video title or publish metadata must not be used to synthesize a new filename. Store videoId once at the shard root; segment records inherit it and must not contain their own videoId.
4. Add segment records with a stable route slug, source-backed start, optional end, sourcePath, and evidence. Do not add a separate segment id; the loader derives the runtime identifier from slug.
5. Use kind: qa only when the transcript contains an actual prompt and answer. Do not invent Q&A from lecture material.
6. Check the canonical source type before applying ordinary density guidance. The first-pass Q&A scan applies to recorded videos, interviews, premieres, and other non-live sources as well as live streams. Treat every live stream as mixed classroom-style content: inspect the full duration, preserve substantive lecture blocks as chapter or notable_point, and create one kind: qa record for every substantive prompt and response. Each Q&A record needs an accurate start, optional end, concise question, concise answerShort, and evidence.
7. Compare live-stream titles with liveStreamExtraction.explicitQaTitleMarkers in src/derived/site-content-processing.config.json. A marker match makes exhaustive Q&A extraction mandatory but does not force lecture portions into Q&A.
8. Keep summary concise, searchable, and useful as a watch pointer. Use body for reader-facing context, caveats, and why the segment matters.
9. Avoid long transcript quotes; paraphrase and cite the time window.
10. Write the selected shard, run the exact-shard timestamp sorter, and validate the sorted canonical shard. Then pass the scoped wording check and run C:\Program Files\nodejs\npm.cmd run sync:video-topics with elevation on the first attempt. The wording command is C:\Program Files\nodejs\npm.cmd run check:site-content-wording -- --path <canonical shard path> --strict --review. Fix every high-confidence issue and rerun until the scoped command succeeds. Inspect every review candidate against the transcript; preserve legitimate historical, technical, operational, or interpretive wording, and do not use --strict-review or require the review count to reach zero. The repository-wide actionable wording gate also runs inside check:source, but this single-shard skill must not run that broader command. Append exactly one newline-terminated, semicolon-separated data line at the physical bottom of src/derived/site-content-processing.log only after synchronization succeeds. Never prepend the entry or insert it beneath the header. A selected-shard sorting or validation failure, wording-check failure, elevation denial, or synchronization failure means shared-output finalization is incomplete. Keep workflow status in the log rather than in public shard fields. Do not write schedules, reports, generated archives, package files, tooling, Astro/CSS sources, or any other file. An invoking automation may perform only its explicitly defined lane-private bookkeeping after this finalization.
11. For the main transcript pass, do as much useful in-file processing as the configured model and effort can support across the full transcript. Favor coverage and transcript-backed substance over final wording polish, but do not stop at an overview, sample a subset, or deliberately reserve supported chapters or transcript-visible Q&A for a later audit. Disclose unresolved chapter ranges, Q&A, audiovisual work, and other limitations plainly in the processing-log result and notes and in the handoff.
12. Let the transcript determine segment count for every video. Do not target a minimum, maximum, or preferred numeric range. Split when the subject, argument, example, or Q&A exchange meaningfully changes; avoid both broad catch-all notes and artificial padding.
13. Derive significant segment topic slugs from the transcript. Add evidence-backed slugs needed to describe ships, classes, navies, states, empires, peoples, armies, aircraft, battles, campaigns, leaders, weapons, railways, ports, places, trade routes, supply systems, policies, doctrine, logistics, institutions, and time periods without targeting a tag count or limiting the pass to a fixed starter taxonomy. Preserve useful specificity for the later auditor; leave registry creation, titles, default summaries, and routine consistency checks to the deterministic synchronizer.
14. Use src/derived/topic-normalization-patterns.tsv as the detailed source of truth for steady-state topic creation, display names, aliases, and exceptions. Resolve every new slug through active rules whose scope includes creation. Preserve evidence-backed subject specificity, including distinctions between generic calibres and named systems, and preserve established slugs unless the active creation policy canonicalizes them. Leave review, disabled, ambiguous, or inapplicable matches unchanged and identify unresolved review candidates in the handoff.
15. Use a fiction-... slug when the topic referent exists only inside a fictional work, including fictional vessels, people, factions, events, technologies, and in-universe systems. Do not put counterfactual real history, real proposed or unbuilt designs, possible future systems, or genre/format topics in that namespace. When Dr. Clarke uses fiction to explain a real-world point, tag both the fictional referent and the ordinary transcript-backed doctrine, engineering, logistics, institutional, or other concepts it illustrates.

Public fields must not expose workflow status. Do not put "first pass", "later extraction", "processing", "curation", "search metadata", "source window", "evidence window", "seed", "prototype", or "this segment exists to..." language in title, summary, body, question, or answerShort when it describes the site or content pipeline. The same words are allowed when the related transcript specifically uses them in the same subject-matter sense, such as warship prototypes, electoral first-past-the-post discussion, or data processing. Put incomplete-work status in the processing log or handoff. Segment body should normally be 4-10 substantive sentences, especially for chapter and notable_point records, with concrete transcript-backed detail rather than a one-line label.

Final Public-Wording Pass

After all transcript-backed content and topic decisions are complete, and before writing and validating the canonical shard:

1. Apply $humanizer in embedded mode. Run its draft, audit, and final loop internally, then use only the final rewrite in the shard. Do not place Humanizer draft text, audit bullets, or a separate Humanizer summary in the JSON, processing log, or handoff.
2. Apply Humanizer to every string value in title, summary, body, question, and answerShort, including video-level and segment-level occurrences. Use a neutral reference and study-guide voice. Read the shard as a continuous human experience, including summaries beside their bodies, rather than treating an individually grammatical field as automatically finished.
3. Treat the transcript and this naval-content skill's evidence-preservation instructions as higher priority than generic Humanizer defaults. Preserve every transcript-backed claim, proper noun, date, number, technical list, qualification, uncertainty, caveat, limitation, real-history-versus-scenario distinction, and whether a point is certain, tentative, or conditional. Attribution wording is not automatically preserved.
4. Every segment already carries sourcePath and evidence, so public host attribution is never needed merely to establish provenance. In a solo-speaker episode, drop routine host attribution and write the subject naturally. This applies equally to explanations, interpretations, judgments, predictions, recommendations, humor, uncertainty, and caution. A solo-speaker segment should normally contain no routine Dr. Clarke, Dr Clarke, Alex Clarke, bare Clarke, the presenter, the speaker, the lecturer, or the host framing. Preserve uncertainty and interpretation through the wording itself instead of repeatedly naming the person who said it. Do not repeat the name in a summary and its body.
5. In multi-speaker material such as an interview, panel, collaborative stream, or Bruships episode, name a speaker only when the reader needs the attribution to follow a change of speaker, disagreement, contrast, or quotation. Once the identity is clear, return to natural subject-first prose.
6. Before writing, scan all public fields in the whole shard for Clark, Clarke, and the generic speaker labels above. Identify the person behind every surname match from the transcript before editing. Rewrite routine references to Dr. Alex Clarke in a solo-speaker episode unless an actual quotation needs identification. Preserve other people named Clark or Clarke. If check:site-content-wording reports host-attribution, inspect every hit. A solo-speaker shard may retain the review finding only when every surviving match names another person or identifies a quotation that genuinely needs an owner. In multi-speaker material, also retain attribution needed to distinguish speakers.
7. During this wording phase, leave slugs, kinds, starts, ends, timestamps, topics, sourcePath, evidence, key order, array order, JSON structure, and all other fields unchanged. Do not rewrite existing processing-log text. Required finalization may append its one new row after the checks succeed.
8. Review the fields one at a time and recheck every rewrite against its cited transcript passage. Check video-level title and summary wording against the full transcript and the evidence supporting its segments. Reject or revise wording that adds, removes, strengthens, weakens, or reattributes a claim.
9. Write the final field values, then run the timestamp sorter for the selected shard, perform canonical shard validation, the scoped wording check, topic synchronization, and processing-log finalization in the required order below. The sorter is the ordering mechanism; do not replace it with a manual ordering check.

Shared-Output Finalization

1. Finish the full transcript read and topic-policy decisions, apply the justified changes directly to the selected shard, and write it. Do not perform a pre-write drift check.

2. Run the sorter once for that exact shard from the repository root:

   bun run ./src/scripts/sort-video-segments-by-start.ts ./src/derived/video-segments/<manifest.fileStem>.json

   Run it with sandbox_permissions: require_escalated on the first attempt to avoid sandbox EPERM failures. The sorter writes only the selected shard. On Sorted or Already sorted, continue to canonical validation. If it reports malformed timestamps or fails while sorting, use its console diagnostics to repair only the selected shard from transcript evidence, then rerun it. An unresolved selected-shard sorting failure blocks finalization.

3. Validate the canonical shard after the sorter has sorted or confirmed it.

4. Run C:\Program Files\nodejs\npm.cmd run check:site-content-wording -- --path <canonical shard path> --strict --review. Resolve every high-confidence finding, adjudicate every review candidate against the transcript, and rerun the command until it exits successfully. Keep review candidates when they are genuine subject-matter wording; their count does not need to reach zero.

5. Run C:\Program Files\nodejs\npm.cmd run sync:video-topics with sandbox_permissions: require_escalated on the first attempt. Ask for approval with a concise topic-synchronization justification and use the narrow reusable prefix for that npm command when the runtime supports one. Do not make a sandboxed attempt first. If elevation is denied or synchronization fails, leave the completed shard write in place, do not append the log, and report the shared-output blocker.

6. Do not attribute the synchronizer's corpus-wide added N topics result to only the selected shard.

7. If synchronization reports a noncanonical slug, review candidate, invalid topic, or other topic problem caused by the selected shard, correct the shard from transcript evidence and active policy, validate it, rerun the scoped wording check, and rerun the same elevated synchronization command. If the blocker cannot be resolved in scope, do not append a completion row.

8. Append the four-field processing-log row only after the sorter result, canonical shard validation, scoped wording check, and synchronization succeed. A selected-shard sorting or validation failure, wording-check failure, elevation denial, or synchronization failure blocks the completion row without invalidating the completed shard write.

Processing Log Contract

• A successful elevated npm run sync:video-topics run is a precondition for the completion row. The registry result may be added N topics or already current; record it in the handoff, not as an extra log field.

• Before appending, read and verify that the existing first line is exactly timestamp;shardPath;result;notes. If the file or header is missing or invalid, stop and report the blocker instead of creating or repairing the log.

• Construct the row as exactly four nonempty field values in this order: an exactly 19-character local timestamp formatted yyyy-MM-ddTHH:mm:ss; canonical shard path; concise result; concise notes. Do not write fractional seconds, a trailing Z, or a numeric UTC offset, and never use round-trip formats such as Get-Date -Format o. Describe any unresolved coverage or audiovisual work plainly in result and notes and in the handoff.

• Use this low-freedom PowerShell pattern, supplying the four variables with the actual curation result:

  $timestamp = Get-Date -Format 'yyyy-MM-ddTHH:mm:ss'
  if ($timestamp.Length -ne 19 -or $timestamp -cnotmatch '^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$') { throw 'Processing-log timestamp must be exactly yyyy-MM-ddTHH:mm:ss with no fraction or timezone suffix.' }
  $fields = @($timestamp, $shardPath, $result, $notes)
  if ($fields.Count -ne 4 -or $fields.Where({ [string]::IsNullOrWhiteSpace($_) }).Count -gt 0) { throw 'Processing-log row requires four nonempty fields.' }
  if ($fields.Where({ $_ -match '[;\r\n]' }).Count -gt 0) { throw 'Processing-log fields must not contain semicolons or line breaks.' }
  $line = $fields -join ';'
  Add-Content -LiteralPath 'src/derived/site-content-processing.log' -Value $line -Encoding utf8

• Do not put semicolons or line breaks inside field values; use commas when internal punctuation is needed. Before appending, confirm $line.Split(';').Count -eq 4. A valid row resembles 2026-07-15T16:10:20;src/derived/video-segments/<manifest.fileStem>.json;12 records added;Full transcript chaptered and answered Q&A covered.

• shardPath must be src/derived/video-segments/<manifest.fileStem>.json, matching the shard written by this skill, not the transcript TXT path or a generated Markdown path. Do not add a separate video-ID field because the manifest-owned shard filename already contains the video ID.

• Never use Set-Content, WriteAllText, output redirection, or any read-modify-rewrite operation for routine logging; never truncate, recreate, replace, remove, or reorder existing log content.

For public wording, prefer human study-guide terms such as video guide, watch point, time note, and video moment. Keep timestamp for technical fields, evidence ranges, source validation, and YouTube URL parameters rather than headline/button/card copy. A good public segment should answer: what subject is covered, what the viewer will learn there, and why that part of the video is worth opening.

Runner Boundary

• Keep reusable site intent, public wording, and segment-density rules in this skill and .agents/transcript-content-curator.md.
• The normal processing unit is one transcript/video content shard per process run in the main working checkout. That is already isolated by design, so do not default to detached worktrees for routine transcript curation.
• A worktree is only useful for broad, risky, or unrelated code changes. For one transcript file -> one content shard, worktrees add merge and stale-state failure modes without much isolation benefit.
• Require the invoking task or automation to identify exactly one transcript and one owned current-schema shard. Do not choose work from a generic backlog or infer ownership from existing files.
• The skill's semantic edits remain limited to the selected shard. Run only the exact-shard timestamp sorter, canonical validation of that shard, the scoped read-only npm run check:site-content-wording -- --path <shard> --strict --review validation, and the deterministic elevated npm run sync:video-topics shared-source update. Never inspect or hand-edit topics.json, edit src/derived/topic-normalization-patterns.tsv, generate reports or archives, install dependencies, run other tests/builds/audits/validation, or perform corpus-wide topic rewrites.
• A schedule automation may separately own an atomic claim, lane-private log, video-specific temporary validation directory, and exact-row completion/reset. Follow those prompt-specific steps without widening them into shared pipeline work. The skill still owns elevated synchronization and the canonical processing-log append unless the invoking automation explicitly supplies an equivalent elevated synchronization and append transaction.
• Run scheduled transcript processing as a single-agent job. Do not use ultra, multi-agent mode, or subagents inside a claimed run. Scheduled workers must refuse src/derived/prototype-segments.json, write only the one owned current-schema shard, use only automation-prompt-owned private checks when supplied, and stop after the one claimed transcript.
• A transcript path or exact automation-claimed row is authoritative. A queue or schedule filename by itself does not select a shard; the invoking automation must perform its own atomic claim before this skill edits content.
• Main-pass curation and follow-up auditing are separate phases, but the main pass must exhaust the useful transcript-backed work it can perform at its configured model and effort. Do not trade coverage for exhaustive wording polish, and do not deliberately leave supported chapters or Q&A for the auditor. Use follow-up passes for content the lower-effort run genuinely missed, stronger-model review, or later substance and wording improvements; identify unfinished coverage precisely in the processing-log result and notes and in the handoff.

Handoff

Report the video ID, transcript path, shard changed, segments added or changed, topic slugs introduced, active creation rules used, unresolved review or ambiguous candidates, transcript coverage status, whether the sorter changed or confirmed the selected shard, the scoped wording-check result and any retained transcript-supported review candidates, that sync:video-topics was invoked with elevation, the exact corpus-wide synchronization result, the processing-log line appended, and any remaining ranges. State that the normalization catalog, manual topic-registry editing, corpus-wide topic rewriting, generation, schedules, reports, other tests, builds, and validation were intentionally not touched. If an invoking automation performed lane-private bookkeeping or temporary checks, report only those prompt-owned results. If the transcript cannot be curated, validated, or synchronized safely, report the blocker and inspected time windows without creating a shared task note or appending a success line.