fix: document subtitle external context support

docs/guides/init.md

@@ -120,7 +120,7 @@ The init command is the entry point for all ArcKit work -- everything starts her
 
 - **Safe to re-run**: If the `projects/` directory already exists, the command detects this and asks before proceeding. It will not overwrite existing artifacts.
 
-- **Place external documents early**: After init, add any existing architecture documents, regulations, or vendor materials to `projects/000-global/external/`. ArcKit commands will read these to inform artifact generation.
+- **Place external documents early**: After init, add any existing architecture documents, regulations, vendor materials, or meeting/video subtitle exports (`.srt`/`.vtt`) to `projects/000-global/external/`. ArcKit commands will read these to inform artifact generation.
 
 - **This is for the plugin workflow**: If you are using the CLI (`arckit init`), the CLI handles initialization differently by also scaffolding `.codex/`, `.opencode/`, and `.arckit/` directories. The `/arckit:init` slash command is specifically for the Claude Code plugin workflow.
 

plugins/arckit-claude/agents/arckit-aws-research.md

@@ -89,7 +89,7 @@ Scan for external (non-ArcKit) documents the user may have provided:
 **Existing AWS Assessments & Cost Reports**:
 
 - **Look in**: `projects/{project}/external/`
-- **File types**: PDF (.pdf), Word (.docx), Markdown (.md), CSV (.csv)
+- **File types**: PDF (.pdf), Word (.docx), Markdown (.md), CSV (.csv), subtitles/transcripts (.srt, .vtt)
 - **What to extract**: Current AWS usage, cost reports, Well-Architected review findings, migration assessments
 - **Examples**: `aws-cost-report.csv`, `well-architected-review.pdf`, `migration-assessment.docx`
 

plugins/arckit-claude/agents/arckit-azure-research.md

@@ -86,7 +86,7 @@ Scan for external (non-ArcKit) documents the user may have provided:
 **Existing Azure Assessments & Cost Reports**:
 
 - **Look in**: `projects/{project}/external/`
-- **File types**: PDF (.pdf), Word (.docx), Markdown (.md), CSV (.csv)
+- **File types**: PDF (.pdf), Word (.docx), Markdown (.md), CSV (.csv), subtitles/transcripts (.srt, .vtt)
 - **What to extract**: Current Azure usage, cost reports, Azure Advisor findings, migration assessments
 - **Examples**: `azure-cost-report.csv`, `azure-advisor-findings.pdf`, `cloud-assessment.docx`
 

plugins/arckit-claude/agents/arckit-datascout.md

@@ -140,7 +140,7 @@ Scan for external (non-ArcKit) documents the user may have provided:
 **Existing Data Catalogues & API Registries**:
 
 - **Look in**: `projects/{project}/external/`
-- **File types**: PDF (.pdf), Word (.docx), Markdown (.md), CSV (.csv), JSON (.json)
+- **File types**: PDF (.pdf), Word (.docx), Markdown (.md), CSV (.csv), JSON (.json), subtitles/transcripts (.srt, .vtt)
 - **What to extract**: Known data sources, API endpoints, data quality assessments, existing integrations
 - **Examples**: `data-catalogue.csv`, `api-registry.json`, `data-audit.pdf`
 

plugins/arckit-claude/agents/arckit-gcp-research.md

@@ -86,7 +86,7 @@ Scan for external (non-ArcKit) documents the user may have provided:
 **Existing Google Cloud Assessments & Cost Reports**:
 
 - **Look in**: `projects/{project}/external/`
-- **File types**: PDF (.pdf), Word (.docx), Markdown (.md), CSV (.csv)
+- **File types**: PDF (.pdf), Word (.docx), Markdown (.md), CSV (.csv), subtitles/transcripts (.srt, .vtt)
 - **What to extract**: Current Google Cloud usage, billing exports, Active Assist findings, migration assessments
 - **Examples**: `gcp-billing-export.csv`, `active-assist-findings.pdf`, `migration-assessment.docx`
 

plugins/arckit-claude/agents/arckit-gov-reuse.md

@@ -106,7 +106,7 @@ Scan for external (non-ArcKit) documents the user may have provided:
 **Existing Reuse Assessments or Technology Audits**:
 
 - **Look in**: `projects/{project}/external/`
-- **File types**: PDF (.pdf), Word (.docx), Markdown (.md)
+- **File types**: PDF (.pdf), Word (.docx), Markdown (.md), subtitles/transcripts (.srt, .vtt)
 - **What to extract**: Previous reuse research, technology audits, existing open-source evaluations
 - **Examples**: `technology-audit.pdf`, `open-source-review.docx`, `existing-reuse-assessment.md`
 

plugins/arckit-claude/agents/arckit-research.md

@@ -106,7 +106,7 @@ Scan for external (non-ArcKit) documents the user may have provided:
 **Market Research Reports & Analyst Briefings**:
 
 - **Look in**: `projects/{project}/external/`
-- **File types**: PDF (.pdf), Word (.docx), Markdown (.md)
+- **File types**: PDF (.pdf), Word (.docx), Markdown (.md), subtitles/transcripts (.srt, .vtt)
 - **What to extract**: Market landscape data, vendor rankings, pricing benchmarks, technology trend analysis
 - **Examples**: `gartner-report.pdf`, `forrester-wave.pdf`, `market-analysis.docx`
 

plugins/arckit-claude/commands-standalone/pages.md

@@ -121,7 +121,7 @@ projects/000-global/
 ├── policies/                # Governance policies
 │   └── *.pdf, *.docx, *.md
 ├── external/                # Enterprise-wide reference documents
-│   └── *.pdf, *.docx, *.md
+│   └── *.pdf, *.docx, *.md, *.srt, *.vtt
 └── {other global documents}
 ```
 
@@ -182,7 +182,8 @@ projects/
 │   └── external/
 │       ├── README.md             # (excluded from listing)
 │       ├── rfp-document.pdf
-│       └── legacy-spec.docx
+│       ├── legacy-spec.docx
+│       └── architecture-board.vtt
 ├── 002-{another-project}/
 │   └── ...
 └── ...

plugins/arckit-claude/commands/pages.md

@@ -118,7 +118,7 @@ projects/000-global/
 ├── policies/                # Governance policies
 │   └── *.pdf, *.docx, *.md
 ├── external/                # Enterprise-wide reference documents
-│   └── *.pdf, *.docx, *.md
+│   └── *.pdf, *.docx, *.md, *.srt, *.vtt
 └── {other global documents}
 ```
 
@@ -190,7 +190,8 @@ projects/
 │   └── external/
 │       ├── README.md             # (excluded from listing)
 │       ├── rfp-document.pdf
-│       └── legacy-spec.docx
+│       ├── legacy-spec.docx
+│       └── architecture-board.vtt
 ├── 002-{another-project}/
 │   └── ...
 └── ...

plugins/arckit-claude/docs/guides/init.md

@@ -120,7 +120,7 @@ The init command is the entry point for all ArcKit work -- everything starts her
 
 - **Safe to re-run**: If the `projects/` directory already exists, the command detects this and asks before proceeding. It will not overwrite existing artifacts.
 
-- **Place external documents early**: After init, add any existing architecture documents, regulations, or vendor materials to `projects/000-global/external/`. ArcKit commands will read these to inform artifact generation.
+- **Place external documents early**: After init, add any existing architecture documents, regulations, vendor materials, or meeting/video subtitle exports (`.srt`/`.vtt`) to `projects/000-global/external/`. ArcKit commands will read these to inform artifact generation.
 
 - **This is for the plugin workflow**: If you are using the CLI (`arckit init`), the CLI handles initialization differently by also scaffolding `.codex/`, `.opencode/`, and `.arckit/` directories. The `/arckit:init` slash command is specifically for the Claude Code plugin workflow.
 

plugins/arckit-claude/scripts/bash/create-project.sh

@@ -128,12 +128,14 @@ Place external reference documents here for ArcKit commands to read as context.
 - Markdown (.md)
 - Images (.png, .jpg) - for diagrams and screenshots
 - CSV (.csv) - for data exports
+- Subtitles/transcripts (.srt, .vtt) - for meetings, talks, and recorded walkthroughs
 - SQL (.sql) - for database schemas
 
 ## What to Put Here
 - RFP/ITT documents
 - Legacy system specifications
 - User research reports
+- Meeting/video transcripts and subtitle exports
 - Previous assessments and audits
 - Database schemas and ERD diagrams
 - Compliance evidence and certificates
@@ -192,13 +194,15 @@ Place organization-wide reference documents here. These are read by commands acr
 - PDF (.pdf), Word (.docx), Markdown (.md)
 - Images (.png, .jpg) - for diagrams and screenshots
 - CSV (.csv) - for data exports
+- Subtitles/transcripts (.srt, .vtt) - for meetings, talks, and recorded walkthroughs
 - SQL (.sql) - for database schemas
 
 ## What to Put Here
 - Enterprise architecture blueprints and reference models
 - Organization-wide technology standards documents
 - Shared compliance evidence and audit reports
 - Cross-project strategy and transformation documents
+- Cross-project meeting/video transcripts and subtitle exports
 - Industry benchmarks and analyst reports
 
 ## How It Works

plugins/arckit-claude/scripts/python/create-project.py

@@ -104,12 +104,14 @@ def main():
 - Markdown (.md)
 - Images (.png, .jpg) - for diagrams and screenshots
 - CSV (.csv) - for data exports
+- Subtitles/transcripts (.srt, .vtt) - for meetings, talks, and recorded walkthroughs
 - SQL (.sql) - for database schemas
 
 ## What to Put Here
 - RFP/ITT documents
 - Legacy system specifications
 - User research reports
+- Meeting/video transcripts and subtitle exports
 - Previous assessments and audits
 - Database schemas and ERD diagrams
 - Compliance evidence and certificates
@@ -169,13 +171,15 @@ def main():
 - PDF (.pdf), Word (.docx), Markdown (.md)
 - Images (.png, .jpg) - for diagrams and screenshots
 - CSV (.csv) - for data exports
+- Subtitles/transcripts (.srt, .vtt) - for meetings, talks, and recorded walkthroughs
 - SQL (.sql) - for database schemas
 
 ## What to Put Here
 - Enterprise architecture blueprints and reference models
 - Organization-wide technology standards documents
 - Shared compliance evidence and audit reports
 - Cross-project strategy and transformation documents
+- Cross-project meeting/video transcripts and subtitle exports
 - Industry benchmarks and analyst reports
 
 ## How It Works

scripts/bash/create-project.sh

@@ -128,12 +128,14 @@ Place external reference documents here for ArcKit commands to read as context.
 - Markdown (.md)
 - Images (.png, .jpg) - for diagrams and screenshots
 - CSV (.csv) - for data exports
+- Subtitles/transcripts (.srt, .vtt) - for meetings, talks, and recorded walkthroughs
 - SQL (.sql) - for database schemas
 
 ## What to Put Here
 - RFP/ITT documents
 - Legacy system specifications
 - User research reports
+- Meeting/video transcripts and subtitle exports
 - Previous assessments and audits
 - Database schemas and ERD diagrams
 - Compliance evidence and certificates
@@ -192,13 +194,15 @@ Place organization-wide reference documents here. These are read by commands acr
 - PDF (.pdf), Word (.docx), Markdown (.md)
 - Images (.png, .jpg) - for diagrams and screenshots
 - CSV (.csv) - for data exports
+- Subtitles/transcripts (.srt, .vtt) - for meetings, talks, and recorded walkthroughs
 - SQL (.sql) - for database schemas
 
 ## What to Put Here
 - Enterprise architecture blueprints and reference models
 - Organization-wide technology standards documents
 - Shared compliance evidence and audit reports
 - Cross-project strategy and transformation documents
+- Cross-project meeting/video transcripts and subtitle exports
 - Industry benchmarks and analyst reports
 
 ## How It Works

scripts/python/create-project.py

@@ -104,12 +104,14 @@ def main():
 - Markdown (.md)
 - Images (.png, .jpg) - for diagrams and screenshots
 - CSV (.csv) - for data exports
+- Subtitles/transcripts (.srt, .vtt) - for meetings, talks, and recorded walkthroughs
 - SQL (.sql) - for database schemas
 
 ## What to Put Here
 - RFP/ITT documents
 - Legacy system specifications
 - User research reports
+- Meeting/video transcripts and subtitle exports
 - Previous assessments and audits
 - Database schemas and ERD diagrams
 - Compliance evidence and certificates
@@ -169,13 +171,15 @@ def main():
 - PDF (.pdf), Word (.docx), Markdown (.md)
 - Images (.png, .jpg) - for diagrams and screenshots
 - CSV (.csv) - for data exports
+- Subtitles/transcripts (.srt, .vtt) - for meetings, talks, and recorded walkthroughs
 - SQL (.sql) - for database schemas
 
 ## What to Put Here
 - Enterprise architecture blueprints and reference models
 - Organization-wide technology standards documents
 - Shared compliance evidence and audit reports
 - Cross-project strategy and transformation documents
+- Cross-project meeting/video transcripts and subtitle exports
 - Industry benchmarks and analyst reports
 
 ## How It Works

tests/plugin/project-context-builder.test.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/**
+ * Smoke tests for plugins/arckit-claude/hooks/project-context-builder.mjs
+ *
+ * Verifies external text assets, including subtitle/transcript files, are
+ * surfaced to ArcKit commands through injected project context.
+ *
+ * Run with: node tests/plugin/project-context-builder.test.mjs
+ */
+
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  buildProjectContext,
+} from '../../plugins/arckit-claude/hooks/project-context-builder.mjs';
+
+test('project context includes subtitle and transcript external files', () => {
+  const root = mkdtempSync(join(tmpdir(), 'arckit-context-'));
+  try {
+    const projectDir = join(root, 'projects', '001-transcripts');
+    const externalDir = join(projectDir, 'external');
+    mkdirSync(externalDir, { recursive: true });
+
+    writeFileSync(
+      join(projectDir, 'ARC-001-REQ-v1.0.md'),
+      `# Requirements\n\n| Field | Value |\n|---|---|\n| **Document ID** | ARC-001-REQ-v1.0 |\n| **Document Type** | REQ |\n`
+    );
+    writeFileSync(join(externalDir, 'README.md'), '# External Documents\n');
+    writeFileSync(join(externalDir, 'architecture-board.vtt'), 'WEBVTT\n\n00:00:00.000 --> 00:00:02.000\nApprove the target architecture.\n');
+    writeFileSync(join(externalDir, 'supplier-demo.srt'), '1\n00:00:00,000 --> 00:00:02,000\nSupplier demonstrates failover.\n');
+
+    const context = buildProjectContext(root);
+
+    assert.ok(context.includes('External documents'));
+    assert.ok(context.includes('architecture-board.vtt'));
+    assert.ok(context.includes('supplier-demo.srt'));
+    assert.ok(!context.includes('README.md'));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});

tests/plugin/test_graph_utils.mjs

@@ -83,6 +83,8 @@ function makeFixture() {
 
   // External file
   writeFileSync(join(projectDir, 'external', 'spec.api.yaml'), 'openapi: 3.0\n');
+  writeFileSync(join(projectDir, 'external', 'meeting-transcript.vtt'), 'WEBVTT\n\n00:00:00.000 --> 00:00:03.000\nArchitecture board discussion.\n');
+  writeFileSync(join(projectDir, 'external', 'walkthrough-subtitles.srt'), '1\n00:00:00,000 --> 00:00:03,000\nLegacy platform walkthrough.\n');
 
   // Global PRIN
   writeFileSync(
@@ -247,9 +249,14 @@ test('withExternals lists external/ files', () => {
     const g = scanAllArtifacts(projectsDir, { withExternals: true });
     assert.ok(g.externalFiles);
     const ext = g.externalFiles['001-fixture'];
-    assert.equal(ext.length, 1);
-    assert.equal(ext[0].filename, 'spec.api.yaml');
-    assert.ok(typeof ext[0].mtimeMs === 'number');
+    assert.equal(ext.length, 3);
+    const filenames = ext.map(f => f.filename).sort();
+    assert.deepEqual(filenames, [
+      'meeting-transcript.vtt',
+      'spec.api.yaml',
+      'walkthrough-subtitles.srt',
+    ]);
+    assert.ok(ext.every(f => typeof f.mtimeMs === 'number'));
   } finally {
     rmSync(root, { recursive: true, force: true });
   }