@qualisoft/ai-skills 1.1.0 → 1.4.0

package/skills/project-init/build.mjs

@@ -29,6 +29,7 @@ import {
   statSync,
   writeFileSync,
 } from "node:fs";
+import { execFileSync } from "node:child_process";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -168,6 +169,193 @@ function loadMockups(docsDir) {
     .map((f) => ({ file: f, href: DESIGN_DIR + "/" + MOCKUP_DIR + "/" + f }));
 }
 
+/* ================================================================== *
+ * 연동 서비스
+ *
+ * 문서 바깥에 있는 것들(저장소·API 문서·협업 도구)이 어디에 붙어 있는지
+ * 한곳에서 본다. 목록이 어디서 오는지는 네 갈래다. **아래일수록 약하다.**
+ *
+ *   1. 설정   `docs.config.json.integrations` — 사람이 적은 것. 언제나 이긴다
+ *   2. 자동   깃 리모트 · 스펙 파일 — 빌드가 직접 본다
+ *   3. 기획   문서 본문에서 잡은 **연동 예정** — 기획에 적혀 있으면 목록에 오른다
+ *   4. 추천   1~3 이 **하나도 없을 때만** 카탈로그 기본값으로 채운다
+ *
+ * 3번이 이 체계의 요점이다. 연동은 기획에서 먼저 정해지고 나중에 붙는다.
+ * 기획서에 "GCP 에 배포한다"고 적어 두었으면 그건 이미 연동 예정이다 —
+ * 사람이 설정 파일에 한 번 더 적게 만들 이유가 없다.
+ * ================================================================== */
+
+/**
+ * `detect` 는 문서 본문에서 찾을 표기다. 서비스 이름이 본문에 있으면 연동 예정으로 본다.
+ * `recommend` 는 아무것도 못 잡았을 때 보여줄 기본 후보다.
+ * 카탈로그에 없는 서비스도 설정에 적으면 그대로 나온다.
+ */
+const LINK_CATALOG = [
+  { id: "github", name: "GitHub", slug: "github", color: "181717", what: "코드 저장소 · 이슈 · PR",
+    recommend: true, detect: ["github", "깃허브"] },
+  { id: "swagger", name: "Swagger", slug: "swagger", color: "85EA2D", what: "API 스펙 · 문서",
+    recommend: true, detect: ["swagger", "openapi", "스웨거"] },
+  { id: "notion", name: "Notion", slug: "notion", color: "000000", what: "회의록 · 업무 위키",
+    recommend: true, detect: ["notion", "노션"] },
+  { id: "figma", name: "Figma", slug: "figma", color: "F24E1E", what: "디자인 원본 · 시안",
+    recommend: true, detect: ["figma", "피그마"] },
+  { id: "slack", name: "Slack", slug: "slack", color: "4A154B", what: "알림 · 커뮤니케이션",
+    recommend: true, detect: ["slack", "슬랙"] },
+  { id: "jira", name: "Jira", slug: "jira", color: "0052CC", what: "이슈 · 스프린트",
+    recommend: true, detect: ["jira", "지라"] },
+
+  /* 아래는 추천 기본값이 아니다 — 기획에 적혀 있을 때만 올라온다 */
+  { id: "gcp", name: "Google Cloud", slug: "googlecloud", color: "4285F4", what: "배포 · 호스팅",
+    detect: ["gcp", "google cloud", "구글 클라우드", "cloud run", "app engine"] },
+  { id: "aws", name: "AWS", slug: "amazonwebservices", color: "232F3E", what: "배포 · 호스팅",
+    detect: ["aws", "amazon web services", "ec2", "s3 버킷"] },
+  { id: "vercel", name: "Vercel", slug: "vercel", color: "000000", what: "배포 · 호스팅",
+    detect: ["vercel", "버셀"] },
+  { id: "cloudflare", name: "Cloudflare", slug: "cloudflare", color: "F38020", what: "CDN · DNS",
+    detect: ["cloudflare", "클라우드플레어"] },
+  { id: "ga4", name: "Google Analytics", slug: "googleanalytics", color: "E37400", what: "측정 · 전환 추적",
+    detect: ["ga4", "google analytics", "구글 애널리틱스"] },
+  { id: "gtm", name: "Google Tag Manager", slug: "googletagmanager", color: "246FDB", what: "태그 운영",
+    detect: ["gtm", "google tag manager", "태그매니저", "태그 매니저"] },
+  { id: "sentry", name: "Sentry", slug: "sentry", color: "362D59", what: "에러 추적",
+    detect: ["sentry", "센트리"] },
+  { id: "kakao", name: "카카오", slug: "kakaotalk", color: "FFCD00", what: "채널 · 알림톡",
+    detect: ["카카오", "알림톡", "kakao"] },
+  { id: "naver", name: "네이버", slug: "naver", color: "03C75A", what: "검색 등록 · 서치어드바이저",
+    detect: ["서치어드바이저", "네이버 웹마스터", "naver search advisor"] },
+  { id: "stripe", name: "Stripe", slug: "stripe", color: "635BFF", what: "결제",
+    detect: ["stripe", "스트라이프"] },
+  { id: "tosspayments", name: "토스페이먼츠", slug: "tosspayments", color: "0064FF", what: "결제",
+    detect: ["토스페이먼츠", "tosspayments", "toss payments"] },
+  { id: "firebase", name: "Firebase", slug: "firebase", color: "DD2C00", what: "인증 · 실시간 DB",
+    detect: ["firebase", "파이어베이스"] },
+  { id: "supabase", name: "Supabase", slug: "supabase", color: "3FCF8E", what: "DB · 인증",
+    detect: ["supabase", "수파베이스"] },
+  { id: "sendgrid", name: "SendGrid", slug: "sendgrid", color: "1A82E2", what: "메일 발송",
+    detect: ["sendgrid", "센드그리드"] },
+  { id: "githubactions", name: "GitHub Actions", slug: "githubactions", color: "2088FF", what: "CI · CD",
+    detect: ["github actions", "깃허브 액션", "ci/cd"] },
+];
+
+/** git@host:a/b.git → https://host/a/b */
+function normalizeRemote(url) {
+  const ssh = url.match(/^git@([^:]+):(.+?)(\.git)?$/);
+  if (ssh) return "https://" + ssh[1] + "/" + ssh[2];
+  return url.replace(/\.git$/, "");
+}
+
+/** 프로젝트 루트에서 알아낼 수 있는 연동만 자동으로 집는다. */
+function detectLinks(docsDir) {
+  const root = dirname(resolve(docsDir));
+  const found = {};
+
+  try {
+    const remote = execFileSync("git", ["-C", root, "remote", "get-url", "origin"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    if (/github\.com/.test(remote)) found.github = { url: normalizeRemote(remote), note: "git origin" };
+  } catch {}
+
+  const specDirs = ["", "docs", "api", "openapi"];
+  for (const d of specDirs) {
+    const dir = d ? join(root, d) : root;
+    if (!existsSync(dir)) continue;
+    const hit = readdirSync(dir).find((f) => /^(openapi|swagger)\.(ya?ml|json)$/i.test(f));
+    if (hit) {
+      found.swagger = { url: (d ? "../" + d + "/" : "../") + hit, note: "스펙 파일 " + (d ? d + "/" : "") + hit };
+      break;
+    }
+  }
+  return found;
+}
+
+/**
+ * 기획 문서 본문에서 **연동 예정**을 잡는다.
+ *
+ * 연동은 설정 파일보다 기획서에 먼저 적힌다 — "GCP 에 배포한다", "카카오 알림톡을 쓴다".
+ * 그걸 사람이 설정에 한 번 더 옮겨 적게 만들 이유가 없으므로 본문에서 직접 읽는다.
+ * 근거(어느 문서에서 잡았는지)를 함께 돌려주어 오탐을 눈으로 판단할 수 있게 한다.
+ */
+function detectPlannedLinks(docs) {
+  const found = {};
+  for (const c of LINK_CATALOG) {
+    if (!c.detect || !c.detect.length) continue;
+    for (const d of docs) {
+      const body = authoredText(d.body || "");
+      const hit = c.detect.find((k) => body.includes(k.toLowerCase()));
+      if (!hit) continue;
+      const title = (d.meta && d.meta.title) || d.id;
+      found[c.id] = { planned: true, note: "기획에 언급됨 — " + title };
+      break;
+    }
+  }
+  return found;
+}
+
+/**
+ * 사람이 **쓴** 본문만 남긴다.
+ *
+ * 빼는 것 세 가지. 전부 실제로 오탐을 냈다.
+ *   - `> **작성 지침**` — 템플릿 지침에 서비스 이름이 예시로 들어 있다.
+ *     같이 읽으면 **빈 새 프로젝트에서도 연동이 잡힌다**
+ *   - 코드 블록 — 설정 예시에 서비스 id 가 들어 있다
+ *   - 인라인 코드 — `openapi` 처럼 **식별자**를 가리키는 표기다.
+ *     "openapi 파일을 찾는다"는 설명이지 "openapi 를 쓴다"가 아니다
+ *
+ * 지침과 식별자는 "이런 걸 적어라"이지 "이걸 쓴다"가 아니다.
+ */
+function authoredText(body) {
+  return body
+    .replace(/```[\s\S]*?```/g, "")
+    .split("\n")
+    .filter((line) => !/^\s*>/.test(line))
+    .join("\n")
+    .replace(/`[^`\n]*`/g, "")
+    .toLowerCase();
+}
+
+/**
+ * 설정 + 자동 감지 + 기획 감지를 합친다. **설정이 항상 이긴다.**
+ * 셋 다 비면 카탈로그의 추천 기본값으로 채운다 — 빈 페이지를 보여주지 않기 위해서다.
+ * 카탈로그에 없는 id도 설정에 적으면 그대로 나온다(name 은 직접 적는다).
+ */
+function loadLinks(docsDir, config, docs = []) {
+  const conf = config.integrations || {};
+  const auto = detectLinks(docsDir);
+  const planned = detectPlannedLinks(docs);
+
+  let ids = [...new Set([...Object.keys(conf), ...Object.keys(auto), ...Object.keys(planned)])];
+  const recommended = ids.length === 0;
+  if (recommended) ids = LINK_CATALOG.filter((c) => c.recommend).map((c) => c.id);
+
+  return ids.map((id) => {
+    const base = LINK_CATALOG.find((c) => c.id === id) || { id, name: id, slug: id, color: "6b7280", what: "" };
+    const c = typeof conf[id] === "string" ? { url: conf[id] } : conf[id] || {};
+    const merged = { ...base, ...(planned[id] || {}), ...(auto[id] || {}), ...c };
+    merged.source = conf[id] ? "설정" : auto[id] ? "자동 감지" : planned[id] ? "기획" : "추천";
+    merged.connected = merged.status ? merged.status === "connected" : Boolean(merged.url);
+    merged.prompt = merged.connected
+      ? merged.name + " 연동(" + (merged.url || "") + ")이 지금 제대로 물려 있는지 점검해줘. " +
+        "끊겼거나 갱신이 필요한 부분을 알려주고, 바뀐 내용은 Docs/docs.config.json 의 integrations." + id +
+        " 에 반영한 뒤 project-init build 를 다시 돌려줘."
+      : "이 프로젝트를 " + merged.name + (merged.what ? "(" + merged.what + ")" : "") + "에 연동하고 싶어. " +
+        "지금 프로젝트 상태와 이미 붙어 있는 연동을 먼저 확인하고, " + merged.name +
+        " 연동에 필요한 준비물과 단계를 순서대로 알려줘. 연동이 끝나면 Docs/docs.config.json 의 integrations." + id +
+        ' 에 url 과 status:"connected" 를 기록하고 project-init build 를 다시 돌려서 문서에 반영해줘.';
+    return merged;
+  });
+}
+
+const LINK_ADD_PROMPT =
+  "연동하고 싶은 서비스가 하나 더 있어: (서비스 이름). 이 프로젝트에 어떻게 붙이면 되는지 알려주고, " +
+  "Docs/docs.config.json 의 integrations 에 항목을 추가한 뒤 project-init build 를 다시 돌려줘.";
+
+/** 로고 타일. CDN이 막힌 환경에서는 이니셜로 떨어진다. */
+const linkLogo = (l) =>
+  '<span class="logo" style="--brand:#' + l.color + '"><i>' + escapeHtml(l.name.charAt(0)) + "</i>" +
+  '<img src="https://cdn.simpleicons.org/' + l.slug + "/" + l.color + '" alt="" loading="lazy" onerror="this.remove()"></span>';
+
 /* ================================================================== *
  * 3단계 — 시안 스냅샷과 규칙 검증
  *
@@ -891,7 +1079,49 @@ function progressClass(percent) {
  * 렌더
  * ================================================================== */
 
-function render(docs, config, trace, discovery = [], design = [], mockups = [], styleguide = null, docsDir = "", build = []) {
+/**
+ * 이 문서가 프로젝트에서 실제로 쓰였는가.
+ *
+ * 기획안을 근거로 메뉴는 만들어졌지만 끝까지 손대지 않는 문서가 생긴다.
+ * 그런 문서를 "작성 중"으로 두면 진행률이 영원히 낮게 깔리고, 무엇이 남은
+ * 일이고 무엇이 애초에 필요 없던 항목인지 구분되지 않는다.
+ *
+ * 판정은 네 신호 중 하나라도 걸리면 '쓰임'이다. 실측하면 갓 만든 문서는
+ * 37~265, 한 번이라도 채운 문서는 996 이상으로 갈라진다.
+ */
+const USAGE_MIN_CHARS = 400;
+
+function docUsed(doc) {
+  // 주 신호는 **내용**이다. 상태나 링크는 템플릿이 만들어 낸 흔적일 수 있다:
+  // log 템플릿은 status 가 approved 로 시작하고, 모든 spec 템플릿은 리스크
+  // 대장으로 가는 링크를 자동으로 건다. 그걸 근거로 삼으면 갓 만든 대장이
+  // 늘 '사용됨'이 된다.
+  if (meaningfulChars(doc.body) >= USAGE_MIN_CHARS) return true;
+
+  // 내용이 적어도 사람이 손댄 흔적이 있으면 사용으로 본다
+  if (doc.meta.template !== "log" && doc.meta.status && doc.meta.status !== "draft") {
+    return true;
+  }
+  const outside = stripCode(doc.body || "");           // 템플릿 예시 ID 는 제외
+  for (const id of doc.refs?.defined || []) {
+    if (outside.includes(id)) return true;
+  }
+  return false;
+}
+
+/** 템플릿 골격(제목·지침·빈 표·TODO)을 뺀 실질 글자 수. */
+function meaningfulChars(body = "") {
+  return body
+    .replace(/^---\n[\s\S]*?\n---\n/, "")
+    .replace(/^#{1,4} .*$/gm, "")
+    .replace(/^\|[\s|:-]*\|\s*$/gm, "")
+    .replace(/TODO\([a-z]+\)/g, "")
+    .replace(/^> .*$/gm, "")
+    .replace(/\|\s*\|/g, "")
+    .replace(/[\s|·—▪•\-*`>]+/g, "").length;
+}
+
+function render(docs, config, trace, discovery = [], design = [], mockups = [], styleguide = null, docsDir = "", build = [], links = []) {
   const byId = new Map([...discovery, ...design, ...docs].map((d) => [d.id, d]));
   const resolveLink = (target) => {
     const d = byId.get(target);
@@ -910,14 +1140,17 @@ function render(docs, config, trace, discovery = [], design = [], mockups = [],
     g.docs.push(d);
   }
 
-  const navLink = (id, label, status) =>
-    '<a class="nav-item" data-id="' +
+  const navLink = (id, label, status, used) =>
+    '<a class="nav-item' +
+    (used === false ? " unused" : "") +
+    '" data-id="' +
     id +
+    (used === undefined ? "" : '" data-used="' + (used ? "1" : "0")) +
     '" href="#/' +
     id +
     '"><span class="nav-dot s-' +
     status +
-    '"></span><span>' +
+    '"></span><span class="nav-label">' +
     escapeHtml(label) +
     "</span></a>";
 
@@ -997,7 +1230,9 @@ function render(docs, config, trace, discovery = [], design = [], mockups = [],
         escapeHtml(p.name) +
         "</div>" +
         p.docs
-          .map((d) => navLink(d.id, d.meta.title || d.id, d.meta.status || "draft"))
+          .map((d) =>
+            navLink(d.id, d.meta.title || d.id, d.meta.status || "draft", docUsed(d)),
+          )
           .join("") +
         "</div>",
     )
@@ -1006,7 +1241,164 @@ function render(docs, config, trace, discovery = [], design = [], mockups = [],
     stageTitle(4, "구현") + '<div class="nav-empty">' +
     (progress[4] ? "구현 진행 중" : "아직 산출물 없음") + "</div></div>";
 
-  /* --- 문서 본문 (1단계 기록 + 2단계 문서) --- */
+
+  /* --- 연동 서비스 --- */
+  /* 좌측에는 **관리 메뉴 하나만** 둔다.
+     서비스를 전부 나열하면 문서 메뉴보다 길어져 사이드바가 연동 목록판이 된다.
+     목록은 연동 서비스 페이지가 맡는다. 여기서는 몇 개가 붙었는지만 보여준다. */
+  const linkedCount = links.filter((l) => l.connected).length;
+  const linksNav =
+    '<div class="nav-group nav-links">' +
+    '<a class="nav-item" data-id="__links" href="#/__links">' +
+    '<span class="nav-dot s-utility"></span><span>연동 서비스 관리</span><span class="nav-progress ' +
+    progressClass(links.length ? Math.round((linkedCount / links.length) * 100) : 0) + '">' +
+    linkedCount + "/" + links.length + "</span></a>" +
+    "</div>";
+
+  const SRC_PILL = { "설정": "s-approved", "자동 감지": "s-review", "기획": "s-review", "추천": "s-draft" };
+  const linkCard = (l) =>
+    '<div class="link-card' + (l.connected ? " on" : "") + '">' +
+    '<div class="link-head">' + linkLogo(l) +
+    '<span class="link-name">' + escapeHtml(l.name) + "</span>" +
+    '<span class="pill ' + (SRC_PILL[l.source] || "s-draft") + '">' + escapeHtml(l.source || "") + "</span>" +
+    '<span class="pill ' + (l.connected ? "s-approved" : "s-draft") + '">' +
+    (l.connected ? "연결됨" : "미연동") + "</span></div>" +
+    '<p class="card-summary">' + escapeHtml(l.what || "") +
+    (l.note ? " — " + escapeHtml(l.note) : "") + "</p>" +
+    (l.url ? '<div class="link-url">' + escapeHtml(l.url) + "</div>" : "") +
+    '<div class="link-actions">' +
+    (l.connected && l.url
+      ? '<a class="link-btn primary" href="' + escapeHtml(l.url) + '" target="_blank" rel="noreferrer">열기 ↗</a>'
+      : "") +
+    '<button class="link-btn" type="button" data-copy="' + escapeHtml(l.prompt) + '">' +
+    (l.connected ? "점검 요청 복사" : "연동 방법 묻기 복사") + "</button></div></div>";
+
+  const linksArticle =
+    '<article class="doc" data-id="__links" data-title="연동 서비스"><div class="doc-inner"><div class="doc-body">' +
+    "<h1>연동 서비스</h1>" +
+    '<p class="home-lead">이 프로젝트가 밖으로 물려 있는 곳들입니다. ' +
+    "연결된 카드는 눌러서 바로 이동하고, 아직 안 붙은 카드는 <strong>연동 방법 묻기</strong>를 눌러 " +
+    "문구를 복사한 뒤 AI에게 그대로 물어보면 됩니다.</p>" +
+    (links.every((l) => l.source === "추천")
+      ? '<p class="home-lead links-hint"><strong>아직 정해진 연동이 없어 추천 목록을 보여줍니다.</strong> ' +
+        "기획 문서에 쓸 서비스를 적으면(예: “GCP 에 배포한다”) 다음 빌드부터 이 자리에 그것이 올라옵니다. " +
+        "확정된 것은 <code>Docs/docs.config.json</code> 의 <code>integrations</code> 에 적습니다.</p>"
+      : '<p class="home-lead links-hint">목록은 <strong>설정 → 자동 감지 → 기획 본문</strong> 순으로 모읍니다. ' +
+        "<code>기획</code> 딱지가 붙은 카드는 문서에 언급되어 자동으로 올라온 것이라 " +
+        "오탐일 수 있습니다 — 아니면 <code>integrations</code> 에서 빼면 됩니다.</p>") +
+    '<div class="links-grid">' +
+    links.map(linkCard).join("") +
+    '<div class="link-card link-add"><div class="link-head"><span class="logo logo-add"><i>+</i></span>' +
+    '<span class="link-name">새 서비스 추가</span></div>' +
+    '<p class="card-summary">카탈로그에 없는 서비스도 붙일 수 있습니다.</p>' +
+    '<div class="link-actions"><button class="link-btn" type="button" data-copy="' +
+    escapeHtml(LINK_ADD_PROMPT) + '">추가 문의 문구 복사</button></div></div>' +
+    "</div></div></div></article>";
+
+  /* 산출물 대본.
+ *
+ * 코드가 아니라 **AI 에게 주는 지시문**이다. 복사해서 에이전트에 붙여 넣으면
+ * 그 형식으로 산출물을 만든다.
+ *
+ * 대본은 네 겹으로 쌓인다:
+ *   _shape   문서 종류별 구성 — 이 문서는 무엇을 앞에 세워야 하는가
+ *   _purpose 목적 블록 — 받는 사람이 첫 화면에서 무엇을 알아야 하는가
+ *   _scope   고객 송부용 정제 — 무엇을 빼는가
+ *   _style   시각 규격 — 색·글자·표. 값이 고정이라 매번 같은 모양이 나온다
+ *
+ * 대본은 원본 .md 경로만 가리킨다. 내용을 품지 않으므로 문서를 고친 뒤 같은
+ * 대본을 다시 쓰면 최신 내용으로 만들어진다. HTML 크기도 문서 수와 무관하다. */
+const SCRIPT_FORMATS = [
+  { id: "pdf",   label: "PDF",               ext: "pdf" },
+  { id: "excel", label: "Excel (XLSX)",      ext: "xlsx" },
+  { id: "pptx",  label: "PowerPoint (PPTX)", ext: "pptx" },
+  { id: "docx",  label: "Word (DOCX)",       ext: "docx" },
+  { id: "csv",   label: "CSV",               ext: "csv" },
+];
+
+/* 문서 종류별 구성 지침.
+ *
+ * 같은 서식이어도 산출물의 뼈대는 문서마다 다르다. 일정표는 기간이 보여야 하고
+ * 요구사항 대장은 무엇이 어디로 이어지는지가 보여야 한다. 이 지침이 없으면
+ * "원본 순서대로 옮긴 파일"이 나오고, 받는 사람은 무엇을 보라는 것인지 모른다.
+ *
+ * 키는 문서 name(모듈에 적힌 것)이다. 없으면 기본 지침을 쓴다. */
+const DOC_SHAPE = {
+  "deliverable-register":
+    "이 문서는 **납품 목록**입니다. 공정별로 묶고, 각 산출물의 `필수 여부`·" +
+    "`고객 공유`·`상태`가 한눈에 보이게 하세요. 맨 앞 수치는 `전체 종수`, " +
+    "`필수`, `작성 완료`, `미착수` 입니다. **제외한 산출물** 목록을 빠뜨리지 " +
+    "마세요 — 고객이 '이건 왜 없냐'고 묻는 지점입니다. 버전 이력은 맨 뒤에 둡니다.",
+  "wbs-schedule":
+    "이 문서는 **일정표**입니다. 공정 → 과업 2단으로 묶고, 각 과업의 시작·종료·" +
+    "담당·진척이 한 행에 보이게 하세요. 맨 앞 수치는 `전체 과업`, `종합 진척률`, " +
+    "`진행 중`, `지연` 입니다. **마일스톤은 본표와 분리해 따로 세우세요** — " +
+    "고객이 가장 먼저 보는 것이 보고·승인 시점입니다. 지연 과업은 굵게 표시합니다.",
+  requirements:
+    "이 문서는 **요구사항 추적표**입니다. 각 요구사항이 `어느 과업`으로 가고 " +
+    "`어느 산출물`로 확인되는지가 같은 행에 보여야 합니다. 맨 앞 수치는 " +
+    "`전체 요구사항`, `수용`, `추가 검토`, `미수용` 입니다. 부서별로 묶으면 " +
+    "현업이 자기 것을 찾기 쉽습니다. **수용하지 않은 요구사항과 그 이유**를 " +
+    "반드시 포함하세요.",
+  "project-brief":
+    "이 문서는 **사업 개요**입니다. 목표와 범위가 먼저이고, 특히 `범위 제외`를 " +
+    "분명히 세우세요. 맨 앞 수치는 `목표 수`, `기간`, `이해관계자 수` 입니다. " +
+    "이해관계자는 이름과 역할만 남기고 연락처는 뺍니다.",
+  "screen-spec":
+    "이 문서는 **화면 설계서**입니다. 화면 목록을 먼저 보여주고, 그 뒤에 화면별 " +
+    "상세를 둡니다. 맨 앞 수치는 `전체 화면 수`와 구분별 개수입니다. " +
+    "화면마다 **무엇을 하는 화면인지 한 줄**을 앞에 붙이세요.",
+  "data-model":
+    "이 문서는 **데이터 구조**입니다. 테이블 목록을 먼저, 그 뒤 테이블별 칼럼. " +
+    "맨 앞 수치는 `테이블 수`, `관계 수` 입니다. 고객이 읽을 것이므로 " +
+    "**한글 논리명을 물리명보다 앞에** 두세요.",
+  "qa-test-plan":
+    "이 문서는 **검증 계획**입니다. 무엇을 어떤 기준으로 통과시키는지가 핵심입니다. " +
+    "맨 앞 수치는 `시나리오 수`, `필수 통과 항목`, `일정` 입니다. " +
+    "고객이 직접 하는 확인(UAT)과 우리가 하는 확인을 **구분해서** 세우세요.",
+  "release-ops":
+    "이 문서는 **오픈·운영 안내**입니다. 오픈 절차와 이후 지원 체계가 핵심입니다. " +
+    "맨 앞 수치는 `오픈 예정일`, `교육 대상 인원`, `지원 기간` 입니다. " +
+    "고객이 해야 할 준비를 따로 묶어 세우세요.",
+};
+
+const DOC_SHAPE_DEFAULT =
+  "원본의 절 구성을 따르되, **결론과 전체 그림을 앞으로 올리세요.** " +
+  "표가 여러 개면 가장 중요한 것 하나를 먼저 세우고 나머지를 뒤로 보냅니다. " +
+  "무엇이 가장 중요한지 판단이 안 서면, 행 수가 가장 많은 표가 보통 본표입니다.";
+
+function loadScripts(project) {
+  const dir = join(SKILL_DIR, "templates", "script");
+  const part = (name) => {
+    const path = join(dir, name + ".md");
+    return existsSync(path) ? readFileSync(path, "utf8").trim() : "";
+  };
+  const style = part("_style");
+  if (!style) return null;
+  const purpose = part("_purpose");
+  const scope = part("_scope");
+  const out = {};
+  for (const f of SCRIPT_FORMATS) {
+    const path = join(dir, f.id + ".md");
+    if (!existsSync(path)) continue;
+    out[f.id] = readFileSync(path, "utf8")
+      .replace("__STYLE__", style)
+      .replace("__PURPOSE__", purpose)
+      .replace("__SCOPE__", scope)
+      .split("__PROJECT__").join(project || "이");
+  }
+  return Object.keys(out).length ? out : null;
+}
+
+/** 문서 id(`07-screen-spec`)에서 구성 지침을 찾는다. */
+function docShape(id = "") {
+  const name = id.replace(/^\d+-/, "");
+  return "## 이 문서의 구성\n\n" + (DOC_SHAPE[name] || DOC_SHAPE_DEFAULT);
+}
+
+
+/* --- 문서 본문 (1단계 기록 + 2단계 문서) --- */
+  const scripts = loadScripts(config.project);
   const searchIndex = [];
   const articles = [...discovery, ...design, ...docs]
     .map((d) => {
@@ -1087,7 +1479,17 @@ function render(docs, config, trace, discovery = [], design = [], mockups = [],
         escapeHtml(d.meta.updated || d.meta.date || "—") +
         '</span><span class="meta-sep"></span><span class="mono">' +
         escapeHtml(d.file) +
-        "</span></div>" +
+        "</span>" +
+        (stage1
+          ? ""
+          : '<button class="doc-export" type="button" data-export-file="' +
+            escapeHtml(d.file) +
+            '" data-export-title="' +
+            escapeHtml(d.meta.title || d.id) +
+            '" data-export-id="' +
+            escapeHtml(d.id) +
+            '">파일 스크립트</button>') +
+        "</div>" +
         html +
         definedHtml +
         backHtml +
@@ -1317,9 +1719,15 @@ function render(docs, config, trace, discovery = [], design = [], mockups = [],
     '<span class="search-icon">' + ICON.search + "</span>" +
     '<input id="search" type="search" placeholder="문서 검색" autocomplete="off" spellcheck="false">' +
     '<kbd class="search-kbd">/</kbd></div></div>' +
+    '<div class="nav-tools">' +
+    '<label class="nav-toggle"><input type="checkbox" id="inactiveMode">' +
+    '<span>비활성 관리</span></label>' +
+    '<span class="nav-count" id="inactiveCount"></span>' +
+    "</div>" +
     '<div class="nav" id="nav">' +
     guideNav +
     navLink("__home", "홈", "home") +
+    linksNav +
     navLink("__trace", "추적성 매트릭스", "utility") +
     discoveryNav +
     sidebar +
@@ -1341,10 +1749,44 @@ function render(docs, config, trace, discovery = [], design = [], mockups = [],
     '<div class="doc-body"><h1>검색</h1><div id="results"></div></div></div></article>' +
     guideArticle +
     home +
+    linksArticle +
     mockupArticle +
     traceArticle +
     articles +
     "</main>" +
+    (scripts
+      ? '<div class="modal" id="exportModal" hidden>' +
+        '<div class="modal-back" data-close-export></div>' +
+        '<div class="modal-card" role="dialog" aria-modal="true" aria-labelledby="exportTitle">' +
+        '<div class="modal-head">' +
+        '<div><div class="modal-title" id="exportTitle">파일 스크립트 — 산출물 생성 대본</div>' +
+        '<div class="modal-sub" id="exportSub"></div></div>' +
+        '<button class="icon-btn" type="button" data-close-export aria-label="닫기">\u2715</button>' +
+        "</div>" +
+        '<div class="modal-bar">' +
+        '<label class="modal-label" for="exportFormat">형식</label>' +
+        '<select class="modal-select" id="exportFormat">' +
+        SCRIPT_FORMATS.filter((f) => scripts[f.id])
+          .map((f) => '<option value="' + f.id + '">' + f.label + "</option>")
+          .join("") +
+        "</select>" +
+        '<span class="modal-install" id="exportInstall"></span>' +
+        '<button class="modal-copy" type="button" id="exportCopy">대본 복사</button>' +
+        "</div>" +
+        '<div class="modal-body"><pre class="modal-code" id="exportCode"></pre></div>' +
+        '<div class="modal-foot">복사해서 AI 에게 그대로 붙여 넣으면 됩니다. ' +
+        '대본은 원본 <span class="mono" id="exportFile"></span> 을 가리킬 뿐 내용을 품지 않으므로, ' +
+        "문서를 고친 뒤 같은 대본을 다시 써도 최신 내용으로 만들어집니다." +
+        "</div></div></div>" +
+        '<script id="exportScripts" type="application/json">' +
+        JSON.stringify({
+          scripts: scripts,
+          formats: SCRIPT_FORMATS,
+          shapes: Object.fromEntries(docs.map((d) => [d.id, docShape(d.id)])),
+        })
+          .replace(/</g, "\\u003c") +
+        "<\/script>"
+      : "") +
     '<script id="searchIndex" type="application/json">' +
     JSON.stringify(searchIndex).replace(/</g, "\\u003c") +
     "<\/script>" +
@@ -1380,6 +1822,82 @@ const CSS = `
   --s-draft:#979a9b; --s-review:#d9730d; --s-approved:#4dab9a;
   --alert-bg:#2d1f1c; --alert-line:#5c332a; --alert-tx:#ff9b8a;
 }
+
+/* ── 파일 스크립트 버튼 · 모달 ─────────────────────────────── */
+.doc-export{margin-left:auto; font:inherit; font-size:12px; font-weight:500;
+  color:var(--tx-dim); background:transparent; border:1px solid var(--line-strong);
+  border-radius:6px; padding:3px 10px; cursor:pointer; white-space:nowrap;
+  transition:background .12s, color .12s, border-color .12s}
+.doc-export:hover{background:var(--hover); color:var(--tx); border-color:var(--tx-faint)}
+.modal[hidden]{display:none}
+.modal{position:fixed; inset:0; z-index:90; display:flex; align-items:center;
+  justify-content:center; padding:24px}
+.modal-back{position:absolute; inset:0; background:rgba(15,15,15,.45);
+  backdrop-filter:blur(2px); animation:mfade .16s var(--ease)}
+.modal-card{position:relative; display:flex; flex-direction:column;
+  width:min(880px,100%); max-height:min(86vh,760px); background:var(--bg);
+  border:1px solid var(--line-strong); border-radius:14px; overflow:hidden;
+  box-shadow:0 24px 64px rgba(15,15,15,.22); animation:mrise .2s var(--ease)}
+@keyframes mfade{from{opacity:0}}
+@keyframes mrise{from{opacity:0; transform:translateY(10px) scale(.985)}}
+.modal-head{display:flex; align-items:flex-start; gap:16px; padding:18px 20px 14px;
+  border-bottom:1px solid var(--line)}
+.modal-title{font-size:16px; font-weight:600; letter-spacing:-.01em}
+.modal-sub{font-size:12.5px; color:var(--tx-dim); margin-top:2px}
+.modal-head .icon-btn{margin-left:auto; flex:none}
+.modal-bar{display:flex; align-items:center; gap:10px; flex-wrap:wrap;
+  padding:12px 20px; background:var(--bg-side); border-bottom:1px solid var(--line)}
+.modal-label{font-size:12px; color:var(--tx-dim); font-weight:500}
+.modal-select{font:inherit; font-size:13px; color:var(--tx); background:var(--bg);
+  border:1px solid var(--line-strong); border-radius:7px; padding:5px 10px; cursor:pointer}
+.modal-install{font-family:var(--mono,ui-monospace,SFMono-Regular,Menlo,monospace);
+  font-size:11.5px; color:var(--tx-dim); background:var(--bg-code);
+  border-radius:5px; padding:3px 8px}
+.modal-copy{margin-left:auto; font:inherit; font-size:12.5px; font-weight:600;
+  color:#fff; background:var(--accent); border:0; border-radius:7px;
+  padding:6px 14px; cursor:pointer}
+.modal-copy:hover{filter:brightness(1.06)}
+.modal-body{overflow:auto; background:var(--bg-code)}
+.modal-code{margin:0; padding:18px 20px; font-size:12px; line-height:1.65;
+  white-space:pre; color:var(--tx);
+  font-family:var(--mono,ui-monospace,SFMono-Regular,Menlo,monospace)}
+.modal-foot{padding:11px 20px; font-size:12px; color:var(--tx-dim);
+  border-top:1px solid var(--line)}
+@media(max-width:700px){
+  .modal{padding:10px}
+  .modal-copy{margin-left:0}
+  .modal-code{font-size:11px}
+}
+
+/* ── 비활성 메뉴 ─────────────────────────────────────────── */
+.nav-tools{display:flex; align-items:center; gap:8px; padding:2px 14px 8px}
+.nav-toggle{display:inline-flex; align-items:center; gap:6px; cursor:pointer;
+  font-size:11.5px; color:var(--tx-faint); user-select:none}
+.nav-toggle input{width:12px; height:12px; margin:0; cursor:pointer; accent-color:var(--accent)}
+.nav-toggle:hover{color:var(--tx-dim)}
+.nav-count{margin-left:auto; font-size:10.5px; color:var(--tx-faint); font-variant-numeric:tabular-nums}
+/* 한 번도 쓰이지 않은 메뉴 — 노란 점이 아니라 검정 점으로 죽여 둔다 */
+.nav-item.unused .nav-dot,
+.nav-group.p-yellow .nav-item.unused .nav-dot,
+.nav-group.p-red .nav-item.unused .nav-dot,
+.nav-group.p-orange .nav-item.unused .nav-dot,
+.nav-group.p-green .nav-item.unused .nav-dot,
+.nav-group.p-gray .nav-item.unused .nav-dot{
+  background:#000; box-shadow:0 0 0 1px var(--line-strong)}
+[data-theme=dark] .nav-item.unused .nav-dot,
+[data-theme=dark] .nav-group .nav-item.unused .nav-dot{
+  background:#000; box-shadow:0 0 0 1px rgba(255,255,255,.22)}
+.nav-item.unused .nav-label{color:var(--tx-faint)}
+.nav-item.unused:hover .nav-label{color:var(--tx-dim)}
+/* 관리 모드 */
+body.inactive-mode .nav-item{position:relative; padding-left:30px}
+body.inactive-mode .nav-item .nav-dot{position:absolute; left:18px}
+.nav-check{position:absolute; left:7px; top:50%; transform:translateY(-50%);
+  width:12px; height:12px; margin:0; cursor:pointer; accent-color:var(--accent);
+  display:none}
+body.inactive-mode .nav-check{display:block}
+body.inactive-mode .nav-tools{background:var(--hover); border-radius:7px;
+  margin:0 6px 6px; padding:6px 8px}
 html{-webkit-text-size-adjust:100%}
 body{
   margin:0; background:var(--bg); color:var(--tx);
@@ -1460,6 +1978,29 @@ a{color:inherit}
 .nav-group.nav-stage3{padding-bottom:12px; border-bottom:1px solid var(--line)}
 .panel-stage3{border-color:var(--stage3)}
 .panel-stage3 .panel-title{color:var(--stage3)}
+.logo{position:relative; width:18px; height:18px; flex:none; border-radius:4px; background:#fff;
+  border:1px solid var(--line-strong); overflow:hidden}
+.logo i{position:absolute; inset:0; display:grid; place-items:center; font-style:normal;
+  font-size:10px; font-weight:700; color:var(--brand,#555)}
+.logo img{position:relative; display:block; width:100%; height:100%; padding:3px; object-fit:contain}
+.logo-add i{color:var(--tx-faint); font-size:13px}
+.links-grid{display:grid; grid-template-columns:repeat(auto-fill,minmax(250px,1fr)); gap:10px; margin-top:22px}
+.link-card{display:flex; flex-direction:column; gap:6px; padding:14px 16px;
+  border:1px solid var(--line-strong); border-radius:8px; background:var(--bg)}
+.link-card.on{border-color:var(--green)}
+.link-card.link-add{border-style:dashed}
+.link-head{display:flex; align-items:center; gap:8px}
+.link-head .logo{width:22px; height:22px}
+.link-name{font-weight:600; font-size:14px}
+.link-head .pill{margin-left:auto}
+.link-head .pill ~ .pill{margin-left:0}
+.link-url{font-size:11.5px; color:var(--tx-faint); word-break:break-all}
+.link-actions{display:flex; gap:6px; margin-top:auto; padding-top:6px}
+.link-btn{display:inline-flex; align-items:center; justify-content:center; padding:5px 10px;
+  border:1px solid var(--line-strong); border-radius:6px; background:transparent; cursor:pointer;
+  font:inherit; font-size:12px; color:var(--tx-dim); text-decoration:none; white-space:nowrap}
+.link-btn:hover{background:var(--hover); color:var(--tx)}
+.link-btn.primary{border-color:var(--accent); color:var(--accent)}
 .mockups{display:grid; grid-template-columns:repeat(auto-fill,minmax(230px,1fr)); gap:10px; margin-top:20px}
 .mockup{display:flex; align-items:center; justify-content:space-between; gap:10px;
   padding:14px 16px; border:1px solid var(--line-strong); border-radius:8px;
@@ -1643,6 +2184,7 @@ a.panel-row:hover{color:var(--tx)}
   .doc-body h1{font-size:30px}
   .doc-body h2{font-size:21px}
   .cards{grid-template-columns:1fr}
+  .links-grid{grid-template-columns:1fr}
 }
 @media (prefers-reduced-motion:reduce){ *{transition-duration:.01ms !important; animation-duration:.01ms !important} }
 `;
@@ -1709,6 +2251,201 @@ const JS = `
     if(el){ e.preventDefault(); el.scrollIntoView({behavior:'smooth', block:'start'}); }
   });
 
+
+
+  /* ── 비활성 메뉴 관리 ────────────────────────────
+   * 자동 판정(data-used=0)이 기본이고, 사용자가 체크로 덮어쓴다.
+   * index.html 은 빌드마다 새로 만들어지므로 덮어쓴 값은 문서 id 로
+   * localStorage 에 둔다 — 다시 빌드해도 유지된다. */
+  (function(){
+    var box = document.getElementById('inactiveMode');
+    var nav = document.getElementById('nav');
+    var count = document.getElementById('inactiveCount');
+    if(!box || !nav) return;
+    var KEY = 'inactiveDocs';
+
+    function load(){
+      try { return JSON.parse(localStorage.getItem(KEY)) || {}; }
+      catch(e){ return {}; }
+    }
+    function save(map){
+      try { localStorage.setItem(KEY, JSON.stringify(map)); } catch(e){}
+    }
+
+    var overrides = load();
+    var items = [].slice.call(nav.querySelectorAll('.nav-item[data-used]'));
+
+    function isInactive(item){
+      var id = item.getAttribute('data-id');
+      if(Object.prototype.hasOwnProperty.call(overrides, id)) return !!overrides[id];
+      return item.getAttribute('data-used') === '0';
+    }
+
+    function paint(){
+      var n = 0;
+      items.forEach(function(item){
+        var off = isInactive(item);
+        item.classList.toggle('unused', off);
+        var cb = item.querySelector('.nav-check');
+        if(cb) cb.checked = off;
+        if(off) n++;
+      });
+      count.textContent = n ? ('비활성 ' + n + ' / ' + items.length) : '';
+    }
+
+    // 관리 모드에서 쓸 체크박스를 미리 넣어 둔다 (CSS 로 보였다 숨긴다)
+    items.forEach(function(item){
+      var cb = document.createElement('input');
+      cb.type = 'checkbox';
+      cb.className = 'nav-check';
+      cb.title = '비활성으로 표시';
+      item.insertBefore(cb, item.firstChild);
+    });
+
+    /* 체크박스가 <a> 안에 있어 클릭이 그대로 두면 문서 이동까지 간다.
+     * 문서 캡처 단계에서 먼저 가로채 라우터보다 앞서 끊는다. */
+    document.addEventListener('click', function(e){
+      var cb = e.target;
+      if(!cb.classList || !cb.classList.contains('nav-check')) return;
+      e.preventDefault();
+      e.stopPropagation();
+      if(e.stopImmediatePropagation) e.stopImmediatePropagation();
+      var item = cb.closest('.nav-item');
+      if(!item) return;
+      var id = item.getAttribute('data-id');
+      var next = !isInactive(item);
+      var auto = item.getAttribute('data-used') === '0';
+      // 자동 판정과 같아지면 덮어쓰기를 지운다 — 쓸데없는 저장을 남기지 않는다
+      if(next === auto) delete overrides[id];
+      else overrides[id] = next;
+      save(overrides);
+      paint();
+    }, true);
+
+    box.addEventListener('change', function(){
+      document.body.classList.toggle('inactive-mode', box.checked);
+      try { localStorage.setItem('inactiveMode', box.checked ? '1' : ''); } catch(e){}
+    });
+    try {
+      if(localStorage.getItem('inactiveMode')){
+        box.checked = true;
+        document.body.classList.add('inactive-mode');
+      }
+    } catch(e){}
+
+    paint();
+  })();
+
+  /* ── 파일 스크립트 모달 ──────────────────────────── */
+  (function(){
+    var node = document.getElementById('exportScripts');
+    var modal = document.getElementById('exportModal');
+    if(!node || !modal) return;
+    var data = JSON.parse(node.textContent);
+    var sel = document.getElementById('exportFormat');
+    var code = document.getElementById('exportCode');
+    var install = document.getElementById('exportInstall');
+    var sub = document.getElementById('exportSub');
+    var fileEl = document.getElementById('exportFile');
+    var copyBtn = document.getElementById('exportCopy');
+    var cur = { file: '', title: '' };
+    var lastFocus = null;
+
+    function fmt(id){
+      for(var i=0;i<data.formats.length;i++){ if(data.formats[i].id===id) return data.formats[i]; }
+      return data.formats[0];
+    }
+    function stem(file){ return file.replace(/\.[^.]+$/, ''); }
+
+    function render(){
+      var f = fmt(sel.value);
+      var src = data.scripts[f.id] || '';
+      code.textContent = src
+        .split('__SHAPE__').join((data.shapes && data.shapes[cur.id]) || '')
+        .split('__DOC_FILE__').join(cur.file)
+        .split('__DOC_TITLE__').join(cur.title)
+        .split('__DOC_STEM__').join(stem(cur.file));
+      install.textContent = stem(cur.file) + '.' + f.ext;
+      try { localStorage.setItem('exportFormat', f.id); } catch(e){}
+    }
+
+    function open(btn){
+      cur.file = btn.getAttribute('data-export-file') || '';
+      cur.title = btn.getAttribute('data-export-title') || '';
+      cur.id = btn.getAttribute('data-export-id') || '';
+      sub.textContent = cur.title;
+      fileEl.textContent = cur.file;
+      try {
+        var saved = localStorage.getItem('exportFormat');
+        if(saved && data.scripts[saved]) sel.value = saved;
+      } catch(e){}
+      render();
+      lastFocus = btn;
+      modal.hidden = false;
+      document.body.style.overflow = 'hidden';
+      sel.focus();
+    }
+    function close(){
+      modal.hidden = true;
+      document.body.style.overflow = '';
+      if(lastFocus) lastFocus.focus();
+    }
+
+    document.addEventListener('click', function(e){
+      var btn = e.target.closest && e.target.closest('[data-export-file]');
+      if(btn){ e.preventDefault(); open(btn); return; }
+      if(e.target.closest && e.target.closest('[data-close-export]')) close();
+    });
+    document.addEventListener('keydown', function(e){
+      if(e.key === 'Escape' && !modal.hidden) close();
+    });
+    sel.addEventListener('change', render);
+
+    copyBtn.addEventListener('click', function(){
+      var text = code.textContent;
+      var label = copyBtn.textContent;
+      function done(){
+        copyBtn.textContent = '복사됨 ✓';
+        setTimeout(function(){ copyBtn.textContent = label; }, 1600);
+      }
+      function fallback(){
+        var ta = document.createElement('textarea');
+        ta.value = text; ta.setAttribute('readonly','');
+        ta.style.position='fixed'; ta.style.opacity='0';
+        document.body.appendChild(ta); ta.select();
+        try { document.execCommand('copy'); done(); }
+        catch(err){ copyBtn.textContent = '복사 실패'; }
+        ta.remove();
+      }
+      if(navigator.clipboard && navigator.clipboard.writeText){
+        navigator.clipboard.writeText(text).then(done, fallback);
+      } else { fallback(); }
+    });
+  })();
+
+  /* ── 연동 카드: 문구 복사 ──────────────────────── */
+  document.addEventListener('click', function(e){
+    var b = e.target.closest && e.target.closest('[data-copy]');
+    if(!b) return;
+    var text = b.getAttribute('data-copy');
+    var label = b.textContent;
+    function done(){
+      b.textContent = '복사됨 ✓';
+      setTimeout(function(){ b.textContent = label; }, 1600);
+    }
+    function fallback(){
+      var ta = document.createElement('textarea');
+      ta.value = text; ta.setAttribute('readonly','');
+      ta.style.position = 'fixed'; ta.style.opacity = '0';
+      document.body.appendChild(ta); ta.select();
+      try { document.execCommand('copy'); done(); } catch(err) { b.textContent = '복사 실패'; }
+      ta.remove();
+    }
+    if(navigator.clipboard && navigator.clipboard.writeText){
+      navigator.clipboard.writeText(text).then(done, fallback);
+    } else { fallback(); }
+  });
+
   /* ── 전문 검색 ───────────────────────────────────── */
   var search  = document.getElementById('search');
   var results = document.getElementById('results');
@@ -2034,9 +2771,10 @@ function cmdBuild(docsDir) {
   const config = loadConfig(docsDir);
   const mockups = loadMockups(docsDir);
   const styleguide = findStyleguide(docsDir);
+  const links = loadLinks(docsDir, config, docs);
   const trace = buildTraceability([...discovery, ...design, ...docs]);
   const out = join(docsDir, "index.html");
-  writeFileSync(out, render(docs, config, trace, discovery, design, mockups, styleguide, docsDir, build), "utf8");
+  writeFileSync(out, render(docs, config, trace, discovery, design, mockups, styleguide, docsDir, build, links), "utf8");
   console.log(
     "생성됨: " +
       out +