Phase 1

Create import slice and ImportedSource / ImportedExport

Phase 2

Create URL + markdown ingestion endpoint

Phase 3

Project imports into ConceptGroup + ConceptCard

Phase 4

Project cards into:

• skill.md
• human_card_90
• human_card_40
• human_card_11

Phase 5

Project session stacks into:

• tutorial
• guidebook
• youtube script
• live assist

Phase 6

Build markdown browser

→ stored as ImportedSource → projected non-destructively into current entities → exported to md/script/session/assets → browsed in app Do not use this yet: External page → only markdown files → everything else derived ad hoc from local files

15. Strongest fit to your codebase

Given the modules visible now:

• concept-cards
• concept-groups
• session-stacks
• session-paths
• export roadmap already started

The right integration is:

imports = new intake boundary concept-cards/groups = domain persistence session-stacks = composition layer skill/session/script md = export layer markdown browser = read surface

For your deployment reality, prefer:

• DB for authoritative imported/exported content
• optional filesystem mirror for browser/demo/static use

not runtime local-file writes as the only stored source.

If you want, next step can be a concrete Phase 1 code package:

• Prisma models
• createImportFromRequest.ts
• app/(pages)/imports/api/route.ts
• normalizeImportedContent.ts
• initial projectImportToConcepts.ts skeleton

app/ (pages)/ imports/ page.tsx [id]/ page.tsx actions/ createImportFromUrl.ts createImportFromMarkdown.ts processImport.ts projectImportToConcepts.ts projectImportToSkillMd.ts projectImportToAssets.ts projectImportToSessionStack.ts api/ route.ts components/ ImportForm.tsx ImportResultView.tsx types/ imports.types.ts lib/ normalizeImportedContent.ts extractImportBlocks.ts deriveCardsFromImport.ts deriveSkillDocuments.ts deriveSessionStackScript.ts

lib/ export/ renderSkillMd.ts renderSessionMd.ts renderScriptMd.ts renderCardAssetMd.ts

##Prisma addition



model ImportedSource {

id String @id @default(cuid()) sourceType String // "url" | "markdown" | "html" | "manual" sourceRef String? // url or external reference title String? slug String? rawMarkdown String? rawHtml String? rawText String? normalizedMd String? renderedHtml String? status String @default("pending") // pending | processed | failed notes String? meta Json? createdAt DateTime @default(now()) updatedAt DateTime @updatedAt

conceptGroups ImportedConceptGroupLink[] conceptCards ImportedConceptCardLink[] exports ImportedExport[] }

model ImportedConceptGroupLink { id String @id @default(cuid()) importedSourceId String conceptGroupId String role String? // "primary" | "derived"

importedSource ImportedSource @relation(fields: [importedSourceId], references: [id], onDelete: Cascade) conceptGroup ConceptGroup @relation(fields: [conceptGroupId], references: [id], onDelete: Cascade)

@@unique([importedSourceId, conceptGroupId]) }

model ImportedConceptCardLink { id String @id @default(cuid()) importedSourceId String conceptCardId String role String? // "primary" | "derived"

importedSource ImportedSource @relation(fields: [importedSourceId], references: [id], onDelete: Cascade) conceptCard ConceptCard @relation(fields: [conceptCardId], references: [id], onDelete: Cascade)

@@unique([importedSourceId, conceptCardId]) }

model ImportedExport { id String @id @default(cuid()) importedSourceId String exportType String // "skill_md" | "session_md" | "script_md" | "html" | "card_asset" title String? slug String body String renderedHtml String? meta Json? createdAt DateTime @default(now()) updatedAt DateTime @updatedAt

importedSource ImportedSource @relation(fields: [importedSourceId], references: [id], onDelete: Cascade)

@@index([importedSourceId, exportType]) }

type ImportRequest = | { mode: "url"; url: string; output?: Array<"concepts" | "skill_md" | "session_md" | "script_md" | "html" | "assets">; title?: string; groupTitle?: string; } | { mode: "markdown"; markdown: string; title?: string; output?: Array<"concepts" | "skill_md" | "session_md" | "script_md" | "html" | "assets">; groupTitle?: string; } | { mode: "html"; html: string; title?: string; output?: Array<"concepts" | "skill_md" | "session_md" | "script_md" | "html" | "assets">; groupTitle?: string; };

// app/(pages)/imports/api/route.ts import { NextRequest, NextResponse } from "next/server"; import { createImportFromRequest } from "../actions/createImportFromRequest";

export async function POST(req: NextRequest) { try { const body = await req.json(); const result = await createImportFromRequest(body);

return NextResponse.json(result, { status: 200 });

} catch (error) { return NextResponse.json( { ok: false, error: error instanceof Error ? error.message : "Import failed", }, { status: 400 } ); } }

"use server";

import { z } from "zod"; import { prisma } from "@/lib/prisma"; import { fetchUrlAsNormalizedContent } from "../lib/fetchUrlAsNormalizedContent"; import { normalizeImportedContent } from "../lib/normalizeImportedContent"; import { processImport } from "./processImport";

const ImportSchema = z.object({ mode: z.enum(["url", "markdown", "html"]), url: z.string().url().optional(), markdown: z.string().optional(), html: z.string().optional(), title: z.string().optional(), groupTitle: z.string().optional(), output: z .array(z.enum(["concepts", "skill_md", "session_md", "script_md", "html", "assets"])) .optional(), });

export async function createImportFromRequest(input: unknown) { const data = ImportSchema.parse(input);

let title = data.title ?? null; let rawMarkdown: string | null = null; let rawHtml: string | null = null; let rawText: string | null = null; let sourceRef: string | null = null;

if (data.mode === "url") { const fetched = await fetchUrlAsNormalizedContent(data.url!); title = title ?? fetched.title ?? null; rawMarkdown = fetched.markdown ?? null; rawHtml = fetched.html ?? null; rawText = fetched.text ?? null; sourceRef = data.url!; }

if (data.mode === "markdown") { rawMarkdown = data.markdown ?? null; rawText = data.markdown ?? null; }

if (data.mode === "html") { rawHtml = data.html ?? null; rawText = data.html ?? null; }

const normalized = await normalizeImportedContent({ title, rawMarkdown, rawHtml, rawText, });

const imported = await prisma.importedSource.create({ data: { sourceType: data.mode, sourceRef, title: normalized.title, slug: normalized.slug, rawMarkdown, rawHtml, rawText, normalizedMd: normalized.markdown, renderedHtml: normalized.renderedHtml, meta: { requestedOutputs: data.output ?? ["concepts", "skill_md"], groupTitle: data.groupTitle ?? null, }, status: "pending", }, });

const processed = await processImport({ importedSourceId: imported.id, requestedOutputs: data.output ?? ["concepts", "skill_md"], groupTitle: data.groupTitle ?? null, });

return { ok: true, importedSourceId: imported.id, ...processed, }; }

"use server";

import { prisma } from "@/lib/prisma"; import { projectImportToConcepts } from "./projectImportToConcepts"; import { projectImportToSkillMd } from "./projectImportToSkillMd"; import { projectImportToSessionStack } from "./projectImportToSessionStack"; import { projectImportToAssets } from "./projectImportToAssets";

type RequestedOutput = | "concepts" | "skill_md" | "session_md" | "script_md" | "html" | "assets";

export async function processImport({ importedSourceId, requestedOutputs, groupTitle, }: { importedSourceId: string; requestedOutputs: RequestedOutput[]; groupTitle?: string | null; }) { const created: Record<string, unknown> = {};

if (requestedOutputs.includes("concepts")) { created.concepts = await projectImportToConcepts({ importedSourceId, groupTitle, }); }

if ( requestedOutputs.includes("skill_md") || requestedOutputs.includes("session_md") || requestedOutputs.includes("script_md") || requestedOutputs.includes("html") ) { created.documents = await projectImportToSkillMd({ importedSourceId, requestedOutputs, }); }

if (requestedOutputs.includes("assets")) { created.assets = await projectImportToAssets({ importedSourceId, }); }

await prisma.importedSource.update({ where: { id: importedSourceId }, data: { status: "processed" }, });

return created; }

"use server";

import { prisma } from "@/lib/prisma"; import { deriveCardsFromImport } from "../lib/deriveCardsFromImport";

export async function projectImportToConcepts({ importedSourceId, groupTitle, }: { importedSourceId: string; groupTitle?: string | null; }) { const imported = await prisma.importedSource.findUniqueOrThrow({ where: { id: importedSourceId }, });

const derived = deriveCardsFromImport({ title: imported.title ?? "Imported Source", markdown: imported.normalizedMd ?? "", meta: imported.meta, });

const group = await prisma.conceptGroup.create({ data: { title: groupTitle ?? derived.groupTitle, summary: derived.groupSummary ?? null, }, });

await prisma.importedConceptGroupLink.create({ data: { importedSourceId, conceptGroupId: group.id, role: "primary", }, });

const cards = [];

for (const card of derived.cards) { const createdCard = await prisma.conceptCard.create({ data: { title: card.title, hook: card.hook, promise: card.promise, boundaries: card.boundaries, durationMin: card.durationMin, difficulty: card.difficulty, domains: card.domains, intro: card.intro, notes: card.notes, }, });

await prisma.cardContent.create({
  data: {
    conceptCardId: createdCard.id,
    steps: card.steps,
    materials: card.materials,
    structure: card.structure ?? {},
    version: 1,
    language: "en",
  },
});

await prisma.conceptGroupItem.create({
  data: {
    conceptGroupId: group.id,
    conceptCardId: createdCard.id,
  },
});

await prisma.importedConceptCardLink.create({
  data: {
    importedSourceId,
    conceptCardId: createdCard.id,
    role: "primary",
  },
});

cards.push(createdCard);

}

return { groupId: group.id, cardIds: cards.map((c) => c.id), cardCount: cards.length, }; }

This is where your three concerns converge.

Concern A

Generate skill md documents for system / AI assistant instructions

Concern B

Generate human-readable action cards at multiple time-depths: 90, 40, 11

Concern C

Use session stacks as stackable scripts/tutorials/guidebooks/video scripts

All three should be projections from either:

• imported source
• existing concept card group
• existing session stack

Never manually fork content.

export type DeliveryDepth = "full_90" | "medium_40" | "micro_11";

Then each concept card projection can emit:

• skill.md → assistant/system instruction version
• card-90.md → complete tutorial / session card
• card-40.md → compressed workshop / focused practical
• card-11.md → very short action card / quick guide

EXAMPLE -> skill_md human_card_90 human_card_40 human_card_11 session_md script_md html

"use server";

import { prisma } from "@/lib/prisma"; import { renderSkillMd } from "@/lib/export/renderSkillMd"; import { renderSessionMd } from "@/lib/export/renderSessionMd"; import { renderScriptMd } from "@/lib/export/renderScriptMd"; import { renderHumanCardMd } from "@/lib/export/renderHumanCardMd"; import { toExportableCard } from "@/lib/export/toExportableCard"; import { slugify } from "@/lib/slugify";

export async function projectImportToSkillMd({ importedSourceId, requestedOutputs, }: { importedSourceId: string; requestedOutputs: Array<"skill_md" | "session_md" | "script_md" | "html" | "assets" | "concepts">; }) { const links = await prisma.importedConceptCardLink.findMany({ where: { importedSourceId }, include: { conceptCard: { include: { contents: true, conceptGroupItems: { include: { conceptGroup: { include: { conceptGroupItems: { include: { conceptCard: true }, }, }, }, }, }, }, }, }, });

const exportsCreated = [];

for (const link of links) { const card = toExportableCard(link.conceptCard);

if (requestedOutputs.includes("skill_md")) {
  exportsCreated.push(
    await prisma.importedExport.create({
      data: {
        importedSourceId,
        exportType: "skill_md",
        title: card.title,
        slug: `${slugify(card.title)}.skill`,
        body: renderSkillMd(card),
      },
    })
  );
}

if (requestedOutputs.includes("session_md")) {
  exportsCreated.push(
    await prisma.importedExport.create({
      data: {
        importedSourceId,
        exportType: "session_md",
        title: `${card.title} Session`,
        slug: `${slugify(card.title)}.session`,
        body: renderSessionMd(card),
      },
    })
  );
}

if (requestedOutputs.includes("script_md")) {
  exportsCreated.push(
    await prisma.importedExport.create({
      data: {
        importedSourceId,
        exportType: "script_md",
        title: `${card.title} Script`,
        slug: `${slugify(card.title)}.script`,
        body: renderScriptMd(card),
      },
    })
  );
}

exportsCreated.push(
  await prisma.importedExport.create({
    data: {
      importedSourceId,
      exportType: "human_card_90",
      title: `${card.title} 90`,
      slug: `${slugify(card.title)}.90`,
      body: renderHumanCardMd(card, "full_90"),
    },
  })
);

exportsCreated.push(
  await prisma.importedExport.create({
    data: {
      importedSourceId,
      exportType: "human_card_40",
      title: `${card.title} 40`,
      slug: `${slugify(card.title)}.40`,
      body: renderHumanCardMd(card, "medium_40"),
    },
  })
);

exportsCreated.push(
  await prisma.importedExport.create({
    data: {
      importedSourceId,
      exportType: "human_card_11",
      title: `${card.title} 11`,
      slug: `${slugify(card.title)}.11`,
      body: renderHumanCardMd(card, "micro_11"),
    },
  })
);

}

return { count: exportsCreated.length, exportIds: exportsCreated.map((item) => item.id), }; }

This should not be separate authoring. It should compose card exports in order. SessionStack → ordered concept groups → ordered concept cards → each card contributes:

• opener
• explanation
• steps
• prompts
• materials → combined into:
• tutorial.md
• guidebook.md
• live-assistance.md
• youtube-script.md

Good export families for session stacks

• tutorial.md
• process.md
• guidebook.md
• developer-assist.md
• user-assist.md
• youtube-script.md

All of those are just formatting profiles over the same ordered stack content.

So for your concern, yes:

session stacks can become the canonical script-composition layer.

Not just display lists.

This should be read-only and secondary.

Purpose

• inspect generated md
• share results inside the app
• create fast navigable documentation
• avoid external platforms

Recommended source

Do not read raw local files first.

Read from ImportedExport first, then optionally mirror to filesystem later.

Safer order DB export record → optional write to /content/generated/skills/*.md → browser reads DB or mirrored files

markdown file / pasted markdown / fetched page → ImportedSource.normalizedMd → projections

That gives you md-first without forcing all other models to depend on file parsing.

So the early-introduced md structure should be:

• intake format
• projection format
• inspection format

But not yet your only domain truth.

That is the safe compromise.

External ingest POST /imports/api

VIEWS /imports /imports/[id] /skills /skills/[slug] /scripts /scripts/[slug] /sessions/[slug]

type ProjectionProfile = | "assistant_skill" | "human_card_90" | "human_card_40" | "human_card_11" | "tutorial" | "process_doc" | "live_assist" | "guidebook" | "youtube_script";

Version: V0.2 (codebase-grounded) Replaces: ROADMAP.skill-export.md V0.1 (abstract) Status: Planning — ready to implement