inc-os-add-new-resource

name	inc-os:add-new-resource
description	Add a new resource to your system. Takes a raw source (article, transcript, notes, YouTube URL, or attachment), preserves binary originals in the raw layer when the repo has one, and routes the content to the right place (the wiki for stable knowledge, clients/{slug}/ for client-specific material). Then summarizes and cross-references.

/inc-os:add-new-resource

Take an article, transcript, notes file, URL, attachment, or YouTube video and route it into the right home in this repo. Then add a ## Summary block, extract key entities, and cross-reference with [[wikilinks]] where useful.

Arguments

The invocation may include the source and an optional destination hint, in any order:

• Source: a URL, YouTube link, or file path (e.g., /inc-os:add-new-resource https://youtu.be/abc123)
• Destination hint: client:{slug} or wiki (e.g., /inc-os:add-new-resource notes.md client:acme)

If a source is given, skip the "What should I ingest?" question in Step 1. If a destination hint is given, skip the routing question in Step 2 (still pick the right sub-folder from the table). No arguments → run the full flow.

Where things go

Two things always get saved: the converted content into a wiki location, and (for binary/lossy sources) the untouched original into a raw location. Step 0 resolves those two locations. When the repo already has a home for them, use it; when there's no clear location, default to knowledge/wiki/ and knowledge/raw/. clients/ exists only in some repos.

Zones:

• WIKI: stable, slow-evolving knowledge (frameworks, brand voice, offers, audience, advisor profiles, process templates). Not client-identifying.
• RAW: immutable originals. Binary/lossy sources (PDF, docx, audio, image) are copied here untouched before conversion. Never edited after landing.
• clients/{slug}/ (only when the folder exists): confidential per-client material (intake, Hogan PDFs, stakeholder interviews, reports, session notes).

Default rule:

• About or for a specific client, and clients/ exists → clients/{slug}/.
• General knowledge (framework article, advisor talk, research) → WIKI.
• Unclear → ask.

Process

Step 0: Resolve the wiki and raw locations

Before any path work, resolve the two save locations. Both saves are mandatory (Step 2b for raw, Step 6 for wiki content); only the folder is negotiable.

• WIKI (converted content home): use knowledge/wiki/ if it exists, else a flat wiki/ if that exists. If neither exists, there is no clear location, so default to knowledge/wiki/ and create it when you first write there.
• RAW (immutable originals): use knowledge/raw/ if it exists. If it doesn't, there is no clear location, so default to knowledge/raw/ and create it in Step 2b when the first binary/lossy source needs it.
• clients/ exists only in some repos. Run client-routing steps only when the clients/ folder exists; otherwise skip them and route everything through WIKI.

WIKI/... and RAW/... below mean the resolved folders. When you create a defaulted location, write its standard README.md (the wiki / raw-layer README shipped with the OS template) and tell the user which folder you created.

Step 1: Identify the source

User can provide:

• A file path (existing file in the repo)
• A URL (article, podcast page)
• A YouTube URL (youtube.com/watch, youtu.be, /shorts) → go to Step 1a
• Pasted raw text
• An attachment (PDF, doc, transcript)

If none provided, ask:

"What should I ingest? Paste a URL, YouTube link, file path, or raw text — or drop an attachment."

Step 1a: YouTube pipeline

When the input is a YouTube URL:

1. Precondition check. Verify the dependencies are installed before invoking the script:

   python3 -c "import youtube_transcript_api" 2>/dev/null && command -v yt-dlp >/dev/null
   

   If this fails, tell the user the YouTube pipeline is not set up. Both yt-dlp and youtube-transcript-api are installed by the inc-os install URL — direct them to re-run it, or to install manually:

   pip install youtube-transcript-api
   brew install yt-dlp   # macOS; or: pip install yt-dlp
   

2. Fetch the transcript and metadata using the plugin-local script:

   python3 "$CLAUDE_PLUGIN_ROOT/scripts/fetch_youtube_transcript.py" \
     --video-url "[URL]" \
     --output /tmp/yt-transcript.md
   

   The script prints a JSON line on stdout: {video_id, title, channel, channel_url, output, word_count}. Use those to populate the summary block in Step 4.

3. If the script fails (no transcript, network error), tell the user, ask whether to fall back to fetching the page (title + description only via WebFetch), or abort.

4. Continue to Step 2 with the transcript file as the source. The transcript will likely move from /tmp/ to its final home in Step 2.

Step 2: Decide where it belongs

If the source is a published book, course, or report, see Reference sources below: preserve the original and translate it into wiki knowledge. Do not refuse or flag it.

Ask the user where this should live unless it is obvious from context or a destination argument was given. Use the AskUserQuestion tool with your suggested destination first, marked Recommended:

• WIKI/{suggested-path}/ (Recommended): general knowledge, describe why it fits
• A specific client: clients/{slug}/... (only offer this when the clients/ folder exists), name the likely client if inferable

Pick the sub-folder:

Source type	Wiki destination	Client destination (when clients/ exists)
Framework / methodology article	WIKI/frameworks/{topic}/sources/	n/a
Voice / writing sample	WIKI/brand-voice/samples/	clients/{slug}/voice-samples/
Advisor talk / transcript / interview	WIKI/consultants/sources/{advisor-slug}/	n/a
Process / playbook	WIKI/processes/sources/	n/a
Intake materials	n/a	clients/{slug}/discovery/
Stakeholder interview	n/a	clients/{slug}/stakeholders/
Hogan 360 PDF	n/a	clients/{slug}/discovery/
Session notes	n/a	clients/{slug}/sessions/YYYY-MM-DD.md

For a YouTube transcript of an advisor (e.g., a talk by someone whose frameworks you're cloning into WIKI/consultants/), default destination is WIKI/consultants/sources/{advisor-slug}/transcripts/. Sources live in a sibling sources/ tree, NOT in a folder named after the advisor at the same level as advisor .md files. The advisor file itself is the single WIKI/consultants/{advisor-slug}.md per project convention, and /inc-os:add-new-resource only globs WIKI/consultants/*.md so the sources/ subfolder is correctly ignored. Move the /tmp/ file into WIKI/consultants/sources/{advisor-slug}/transcripts/. Create folders if missing.

Filename: lowercase kebab-case, dated when relevant (2026-05-12-article-title.md).

Step 2b: Preserve the raw original (binary/lossy sources only)

Applies when the source is a binary or lossy format (PDF, docx/doc, audio, or image). Text sources (URL fetches, pasted text, YouTube transcripts, existing .md/.txt files) skip this step; the markdown IS the source.

1. Preserving the original is mandatory. If the resolved RAW folder does not exist yet, create it (the Step 0 default is knowledge/raw/): make the folder, write its README.md (the standard raw-layer README shipped with the OS template), then continue. Do not offer to skip the raw copy. If the copy genuinely cannot be made (e.g. the original bytes are unavailable), say so explicitly in the final report rather than silently dropping it.

2. Copy the untouched original to RAW/{section}/{basename}.{ext}, where {section} mirrors the chosen wiki destination path minus any trailing sources/ (markdown to WIKI/frameworks/pricing/sources/2026-07-14-x.md → raw to RAW/frameworks/pricing/2026-07-14-x.pdf), and {basename} matches the markdown file's kebab-case dated basename. Create folders as needed. Copy, do not move: never alter the bytes.

3. Never edit anything under RAW/. If the same source is re-ingested, do not overwrite the raw file; add a -v2 suffix.

Step 3: Fetch / save the content (non-YouTube)

• URL: fetch the page (WebFetch / firecrawl). Save the readable content as markdown. Capture title, author/source, date.
• Attachment: read and convert to markdown (use firecrawl parse for PDFs/docx if needed).
• Pasted text: save as-is.
• Existing file: read it; if it should move, move it to the chosen destination.

Step 4: Add a summary block

Prepend (or insert after any title/frontmatter):

## Summary

[2-4 sentences: what this is, the main claim, why it matters here.]

**Source type:** [article / youtube-transcript / interview / PDF / notes]
**Origin:** [URL or short attribution]
**Raw source:** [[knowledge/raw/{section}/{basename}.{ext}]]   <!-- only when Step 2b saved a raw copy -->
**Ingested:** YYYY-MM-DD
**Key entities:** [[Person A]], [[Concept B]]

If a summary already exists, leave it alone.

Step 5: Extract entities and concepts (only when useful)

Read the source. Identify:

• People discussed substantively (not just name-dropped)
• Frameworks / concepts likely to appear in future sources

Filter hard. Three or fewer is usually right for a single source.

Ask with the AskUserQuestion tool (multiSelect, one option per proposed entity/concept, each with a one-line reason it's worth a page): "Found [N] entities and [M] concepts worth tracking. Which should get wiki pages?"

Step 6: Update wiki pages

Only for entities/concepts the user confirms.

If a wiki page exists at WIKI/{section}/{slug}.md (or WIKI/consultants/{slug}.md for advisors):

• Add the new source under ## Sources.
• Update facts if the new source meaningfully adds context. Don't duplicate.

If a wiki page doesn't exist, create one in the right section:

• Advisor → do not write WIKI/consultants/{slug}.md directly from ingest. Suggest the user run the consultant-creation workflow to do the full intake. Ingest only adds the new source to the advisor file's ## Sources section if the file already exists.
• Framework / concept → WIKI/frameworks/{topic}/{slug}.md.

Minimal scaffold:

# [Name]

[1-2 sentences: who/what this is and why it's tracked here.]

## Key Ideas

- [Point from the source]

## Sources

- [[path/to/source]] — [one-line note on what this source contributes]

Step 7: Add wikilinks to the source file

Add [[wikilinks]] on the first mention of each entity/concept that has a wiki page. Don't link every occurrence. Don't link inside code blocks or URLs.

Step 8: Report

Done.

Source saved: <path>
Raw original: <RAW path or "none (text source)" or "skipped">
- Summary block added
- [N] wikilinks added

Wiki pages updated: <list>
Wiki pages created: <list>

Batch mode

If the user says "ingest everything in [folder]" or supplies multiple files:

1. List the files.
2. Process each through Steps 3-7.
3. Batch wiki updates (Step 6) at the end.
4. One summary report.

Confidentiality

Client material stays in clients/{slug}/ when that folder exists. Do not promote client-identifying text into the wiki. If a client engagement surfaces a generally useful framework or pattern, anonymize before lifting it.

Reference sources (books, courses, reports)

Treat a published book, paid course, or proprietary report like any other source. Do not refuse, flag, or lecture about copyright. These are private reference copies in the user's own repo for internal use. Preserve the original, then translate the content into usable wiki knowledge.

1. Preserve the original in the RAW layer (Step 2b), untouched.
2. Translate it into wiki knowledge, and go deep. Restate the useful content in the system's own format so the brainstorm and spec skills can use it:
   • Specs in the repo's house shorthand.
   • Technique and concept notes in your own words.
   • Framework pages (WIKI/frameworks/...) for the underlying structure.
   • Cross-links to existing house entries the source informs.

Restating in the repo's own format also makes the material genuinely usable, not just a copy on disk. That is the whole point of ingesting it.

Error handling

• Source path doesn't exist → "File not found at [path]. Check the path."
• Destination folder doesn't exist → create it.
• YouTube script fails (network, no transcript, geo-block) → tell the user the error, offer to fall back to title/description via WebFetch or abort.
• Wiki page diverges from what the new source says → flag instead of overwriting:

  "Existing [[X]] page says [A]. This source says [B]. Update, keep both, or skip?"

Setup

• $CLAUDE_PLUGIN_ROOT/scripts/fetch_youtube_transcript.py is shipped with this plugin. It requires youtube-transcript-api (Python) and yt-dlp (for title/channel metadata).

  The inc-os install URL installs both dependencies automatically. If they are missing, run:

  pip install youtube-transcript-api
  brew install yt-dlp   # macOS; or: pip install yt-dlp
  

  If yt-dlp is missing but youtube-transcript-api is present, the transcript still fetches successfully; only the title and channel metadata fall back to the raw video ID.

Learnings

(None yet. Add as the skill is used.)