projectops 4.36.4 → 4.38.0

package/README.md

@@ -6,10 +6,10 @@
 
 [![npm](https://img.shields.io/npm/v/projectops?label=npm)](https://www.npmjs.com/package/projectops) [![Release](https://img.shields.io/github/v/release/Cassiiopeia/projectops?label=release)](https://github.com/Cassiiopeia/projectops/releases) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![Docs](https://img.shields.io/badge/docs-site-4f46e5)](https://cassiiopeia.github.io/projectops/)
 
-**Status: actively maintained.** New versions ship often, sometimes several a day. To stay on a version you have tested, run `npx projectops@<version>` ([releases](https://github.com/Cassiiopeia/projectops/releases)).
+**Status: actively maintained.** npm `latest` is exactly what is on the `main` branch; work in progress on `develop` is never published. Versions can still ship several times a day. To stay on a version you have tested, run `npx projectops@<version>` ([releases](https://github.com/Cassiiopeia/projectops/releases)).
 
 <!-- AUTO-VERSION-SECTION: DO NOT EDIT MANUALLY -->
-## Latest version : v4.36.3 (2026-10-07)
+## Latest version : v4.37.0 (2026-10-10)
 
 [View full version history](CHANGELOG.md)
 
@@ -178,7 +178,7 @@ flowchart TD
     K --> L["/pro-changelog-deploy<br/>Release PR + automerge"]
 ```
 
-> Full list of Skills and usage: **[docs/SKILLS.md](docs/SKILLS.md)** (Korean)
+> Full list of Skills and usage: **[docs/en/skills.md](docs/en/skills.md)**
 
 ### GitHub Actions pipeline
 
@@ -215,14 +215,14 @@ codex plugin marketplace add Cassiiopeia/projectops
 
 The `--mode skills` wizard registers the Codex marketplace and also prepares the native skills fallback. Use `/plugins` only to check or manage the install.
 
-Where the Codex plugin marketplace is unavailable, use the fallback install described in the [Skills guide](docs/SKILLS.md).
+Where the Codex plugin marketplace is unavailable, use the fallback install described in the [Skills guide](docs/en/skills.md).
 
 ```bash
 # Cursor / the full Agent Skills install menu (recommended: npx)
 npx projectops --mode skills
 ```
 
-> Claude Code prefers `/pro-` autocomplete, Gemini prefers its extension, and Codex prefers its plugin marketplace. See the [Skills guide](docs/SKILLS.md) for details.
+> Claude Code prefers `/pro-` autocomplete, Gemini prefers its extension, and Codex prefers its plugin marketplace. See the [Skills guide](docs/en/skills.md) for details.
 
 </details>
 
@@ -257,7 +257,7 @@ Run automation by commenting on an issue or PR.
 | `@projectops ios build` | Build iOS only | Flutter |
 | `@projectops create qa` | Create a QA issue automatically | All projects |
 
-> Details: [PR Preview](docs/PR-PREVIEW.md) | [Flutter builds](docs/FLUTTER-TEST-BUILD-TRIGGER.md) | [Issue automation](docs/ISSUE-AUTOMATION.md)
+> Details: [PR Preview](docs/en/pr-preview.md) | [Flutter builds](docs/FLUTTER-TEST-BUILD-TRIGGER.md) | [Issue automation](docs/en/issue-automation.md)
 
 ---
 
@@ -300,25 +300,25 @@ We would rather tell you up front when this is not a fit.
 - **Releases assume a develop branch → default branch PR flow.** Branch names can be changed in `version.yml`, but it does not suit a repo that does not use two branches.
 - **A personal access token is optional.** You need one only to merge past branch protection or to sync a Projects board. See [Setup](#setup).
 - **It adds about 50 files to your repository** (workflows, helper scripts, templates). See [the measurement](#compared-with-other-tools).
-- **New versions ship often.** Pin a version you have tested with `npx projectops@<version>`.
+- **New versions ship often.** `latest` follows every push to `main` with no delay. Pin a version you have tested with `npx projectops@<version>`.
 - **Server deploy workflows assume a Docker server reachable over SSH.**
 
 ---
 
 ## Documentation
 
-Browse and search everything on the **[docs site](https://cassiiopeia.github.io/projectops/en/)**. Most guides are currently Korean only.
+Browse and search everything on the **[docs site](https://cassiiopeia.github.io/projectops/en/)**. The main guides are in English. A few wizard pages are still Korean only (translations are welcome, see [#799](https://github.com/Cassiiopeia/projectops/issues/799)).
 
 - [Getting started](https://cassiiopeia.github.io/projectops/en/getting-started)
 - [CLI reference](https://cassiiopeia.github.io/projectops/en/cli)
-- [Agent Skills guide (Korean)](https://cassiiopeia.github.io/projectops/SKILLS)
-- [Versioning (Korean)](https://cassiiopeia.github.io/projectops/VERSION-CONTROL)
-- [Changelog automation (Korean)](https://cassiiopeia.github.io/projectops/CHANGELOG-AUTOMATION)
-- [PR Preview (Korean)](https://cassiiopeia.github.io/projectops/PR-PREVIEW)
-- [Issue automation (Korean)](https://cassiiopeia.github.io/projectops/ISSUE-AUTOMATION)
-- [SSH + Docker deploy (Korean)](https://cassiiopeia.github.io/projectops/SSH-DOCKER-DEPLOYMENT-GUIDE)
-- [Flutter CI/CD (Korean)](https://cassiiopeia.github.io/projectops/FLUTTER-CICD-OVERVIEW)
-- [Troubleshooting (Korean)](https://cassiiopeia.github.io/projectops/TROUBLESHOOTING)
+- [Agent Skills guide](https://cassiiopeia.github.io/projectops/en/skills)
+- [Versioning](https://cassiiopeia.github.io/projectops/en/version-control)
+- [Changelog automation](https://cassiiopeia.github.io/projectops/en/changelog-automation)
+- [PR Preview](https://cassiiopeia.github.io/projectops/en/pr-preview)
+- [Issue automation](https://cassiiopeia.github.io/projectops/en/issue-automation)
+- [SSH + Docker deploy](https://cassiiopeia.github.io/projectops/en/ssh-docker-deployment-guide)
+- [Flutter CI/CD](https://cassiiopeia.github.io/projectops/en/flutter-cicd-overview)
+- [Troubleshooting](https://cassiiopeia.github.io/projectops/en/troubleshooting)
 
 ---
 
@@ -327,6 +327,7 @@ Browse and search everything on the **[docs site](https://cassiiopeia.github.io/
 - [Issues](https://github.com/Cassiiopeia/projectops/issues): bug reports and feature requests
   - Finished issues are marked with the `status: done` label and closed automatically when a release is merged (`close_on_release`).
 - [CONTRIBUTING.md](CONTRIBUTING.md): contribution guide
+- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md): how we expect everyone to behave, and where to report problems
 - [SECURITY.md](SECURITY.md): please report security vulnerabilities privately, not in a public issue
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projectops",
-  "version": "4.36.4",
+  "version": "4.38.0",
   "description": "ProjectOps: installer CLI for a fully automated GitHub project management template (versioning, CI/CD, release notes, agent skills)",
   "keywords": [
     "devops",

package/src/cli/args.js

@@ -5,17 +5,18 @@ import { VALID_TYPES } from "../context.js";
 import { SUPPORTED_LANGS, t } from "../i18n/index.js";
 import { REPO_LANGUAGES } from "../core/repo-language.js";
 
-export const DEPLOY_TARGETS = ["docker-ssh", "vercel", "none"];
-export const PUBLISH_TARGETS = ["nexus", "npm", "github-packages"];
-export const LABEL_STYLE_VALUES = ["en", "ko"];
+import { DEPLOY_TARGETS, PUBLISH_TARGETS, INTENT_VALUES, LABEL_STYLES } from "../core/constants.js";
+
+// 값 목록은 core/constants.js 가 정본이다. 기존 import 경로를 깨지 않도록 여기서 다시 내보낸다.
+export { DEPLOY_TARGETS, PUBLISH_TARGETS, INTENT_VALUES };
+export const LABEL_STYLE_VALUES = LABEL_STYLES;
 // 지원 언어의 단일 목록은 repo-language.js 다 (#787). 여기서 따로 들고 있으면 두 벌이 어긋난다.
 export const LANGUAGE_VALUES = REPO_LANGUAGES;
-export const INTENT_VALUES = ["app", "library", "both", "none", "manual"];
 const SEMVER_RE = /^\d+\.\d+\.\d+$/;
 // 유니코드 글자·숫자 허용 (#719) — 공백·셸 메타문자는 문자 클래스에 없어 그대로 거부된다.
 const BRANCH_RE = /^[\p{L}\p{N}][\p{L}\p{N}._/-]*$/u;
 // 허용 실행 모드 (#665) — 오타가 조용히 "복사 0건 성공"으로 끝나지 않게 한다.
-export const MODE_VALUES = ["full", "version", "workflows", "issues", "skills", "doctor", "interactive"];
+export const MODE_VALUES = ["full", "version", "workflows", "issues", "skills", "doctor", "options", "interactive"];
 
 // argv(process.argv.slice(2)) → 파싱 결과. 오류 시 throw(호출부에서 exit 1).
 export function parseArgs(argv) {
@@ -33,6 +34,8 @@ export function parseArgs(argv) {
     includeSecretBackup: null,
     aiPrSummary: null,   // #566 — AI 변경 요약 워크플로우 포함 여부
     projectsSync: null,  // #716 — Projects 보드 동기화 워크플로우 포함 여부 (null=미지정)
+    json: false,         // --json: 기계가 읽는 출력 (--mode options)
+    removeLegacy: false, // #809 — 구세대 배포 워크플로우(confirm 티어)도 .bak 으로 치운다
     pathsCsv: "",            // "flutter=app,react=client" 원문 (정규화는 resolve 단계)
     force: false,
     lang: null,              // --lang en|ko (null = decided by src/i18n resolveLang)
@@ -170,6 +173,8 @@ export function parseArgs(argv) {
       case "--no-ai-summary": result.aiPrSummary = false; break;
       case "--projects-sync": result.projectsSync = true; break;
       case "--no-projects-sync": result.projectsSync = false; break;
+      case "--remove-legacy": result.removeLegacy = true; break;
+      case "--json": result.json = true; break;
       case "--npm-publish":
         process.stderr.write(t("args.npmPublishDeprecated") + "\n");
         result.publishTargets = [...new Set([...(result.publishTargets ?? []), "npm"])];

package/src/cli/help.js

@@ -7,8 +7,9 @@ Usage:
   npx projectops [options]
 
 Options:
-  -m, --mode MODE          Mode (full | version | workflows | issues | skills | doctor)
+  -m, --mode MODE          Mode (full | version | workflows | issues | skills | doctor | options)
                            doctor: diagnose the installation and repository settings (read-only)
+                           options: print every flag and version.yml key; add --json for agents
                            default: interactive
   -t, --type CSV           Project types, comma separated (e.g. spring,react,python)
                            supported: spring flutter react react-native
@@ -26,7 +27,9 @@ Options:
       --secret-backup / --no-secret-backup   Include / exclude the secret backup workflow
       --ai-summary / --no-ai-summary         Include / exclude the PR summary workflow
       --projects-sync / --no-projects-sync   Include / exclude the GitHub Projects status sync workflow (default: off for new installs)
+      --remove-legacy      Rename retired old-generation workflows to .bak (otherwise only listed)
       --nexus / --npm-publish  (deprecated: use --publish nexus / --publish npm)
+      --json               With --mode options: machine-readable output
       --force, -y, --yes   Skip every confirmation and use non-interactive defaults
       --lang en|ko         Display language (default: system language, pinned to en in CI and with --force)
   -v, --version            Print the projectops version
@@ -45,8 +48,9 @@ const HELP_KO = `projectops — GitHub 프로젝트 자동화 템플릿 통합 C
   npx projectops [옵션]
 
 옵션:
-  -m, --mode MODE          통합 모드 (full | version | workflows | issues | skills | doctor)
+  -m, --mode MODE          통합 모드 (full | version | workflows | issues | skills | doctor | options)
                            doctor: 통합 상태·저장소 설정 진단 (읽기 전용)
+                           options: 모든 플래그·version.yml 키 출력 (--json 이면 agent용 JSON)
                            기본: interactive (대화형)
   -t, --type CSV           프로젝트 타입 csv (예: spring,react,python)
                            지원: spring flutter react react-native
@@ -64,7 +68,9 @@ const HELP_KO = `projectops — GitHub 프로젝트 자동화 템플릿 통합 C
       --secret-backup / --no-secret-backup   Secret 백업 워크플로우 포함/제외
       --ai-summary / --no-ai-summary         PR 변경 요약 워크플로우 포함/제외
       --projects-sync / --no-projects-sync   GitHub Projects 상태 동기화 워크플로우 포함/제외 (신규 설치 기본 제외)
+      --remove-legacy      은퇴한 구세대 워크플로우를 .bak 으로 치움 (없으면 목록만 안내)
       --nexus / --npm-publish  (deprecated — --publish nexus / --publish npm 사용)
+      --json               --mode options 와 함께: 기계가 읽는 JSON 출력
       --force, -y, --yes   모든 확인 생략, 비대화형 기본값 사용
       --lang en|ko         화면 언어 (기본: 시스템 언어, CI/--force 는 en 고정)
   -v, --version            projectops 버전 출력

package/src/commands/doctor.js

@@ -19,6 +19,7 @@ import { parseExisting } from "../core/version-yml.js";
 import { verifyInstall } from "../core/verify.js";
 import { readBaseline } from "../core/baseline.js";
 import { detectRepoName } from "../core/detect-fs.js";
+import { detectMigrations } from "../core/migrations/index.js";
 import { t } from "../i18n/index.js";
 
 // 언어 전환(withLang 등) 시점에 평가되도록 함수로 둔다
@@ -149,6 +150,21 @@ export function localChecks(cwd = ".") {
     });
   }
 
+  // 은퇴한 구세대 워크플로우 (#809) — 업데이트는 감지만 하고 남겨 두므로 신형과 함께 돈다.
+  // 예전엔 로그에만 남아 doctor 가 "문제 없음"이라 했다.
+  const legacy = detectMigrations(cwd).confirm;
+  add({
+    name: t("doctor.legacy.name"), purpose: t("doctor.legacy.purpose"),
+    status: legacy.length ? "WARN" : "OK",
+    value: legacy.length ? t("doctor.count", { n: legacy.length }) : t("doctor.none"),
+    detail: legacy.length ? [
+      ...legacy.map((e) => `  ${e.file}${e.replacedBy ? `  →  ${e.replacedBy}` : ""}`),
+      t("doctor.legacy.l1"),
+      ...legacy.map((e) => `  git rm .github/workflows/${e.file}`),
+      t("doctor.legacy.l2"),
+    ] : null,
+  });
+
   const baseline = readBaseline(cwd);
   add({
     name: t("doctor.bl.name"), purpose: t("doctor.bl.purpose"),

package/src/commands/full.js

@@ -5,7 +5,8 @@ import { join } from "node:path";
 import { existsSync, readFileSync } from "node:fs";
 import { writeText } from "../core/fsutil.js";
 import { PATHS } from "../core/paths.js";
-import { buildVersionYml, mergeDeployValues } from "../core/version-yml.js";
+import { installAgentGuide } from "../core/agent-guide.js";
+import { buildVersionYml, mergeDeployValues, resolveUpdatedBy } from "../core/version-yml.js";
 import { markerForType } from "../core/detect.js";
 import { addVersionSectionToReadme } from "../core/copy/readme.js";
 import { copyWorkflows } from "../core/copy/workflows.js";
@@ -29,7 +30,7 @@ export function runFull(context, tempDir, targetRoot = ".", hooks = {}) {
     force = true, now, today, templateVersion = "unknown",
     deployTarget = "docker-ssh", publishTargets = [], includeSecretBackup = false, aiPrSummary = true,
     changelogProvider = "commit", changelogBaseUrl = "", codeReviewCoderabbit = true,
-    deployBranch = "", intent = null, semverAuto = true , appRelease = null, labelStyle = "en", closeOnRelease = null, projectsSync = null, language = "en" } = context;
+    deployBranch = "", intent = null, semverAuto = true , appRelease = null, labelStyle = "en", closeOnRelease = null, projectsSync = null, language = "en", excludedWorkflows = null } = context;
 
   // project_paths 마커 계산 (.sh existing_marker_in_dir 등가 — 대표 마커명)
   const pathMarkers = new Map();
@@ -50,8 +51,9 @@ export function runFull(context, tempDir, targetRoot = ".", hooks = {}) {
     buildVersionYml({
       version, types, paths, pathMarkers, branch, deployBranch, versionCode, now, today,
       deployValues,
+      updatedBy: resolveUpdatedBy(existsSync(vyFile) ? readFileSync(vyFile, "utf8") : "", targetRoot), // #811
       templateOptions: { templateVersion, deployTarget, publishTargets, includeSecretBackup, aiPrSummary, optionsDate: today,
-        changelogProvider, changelogBaseUrl, codeReviewCoderabbit, intent, mode: "full", semverAuto, appRelease, labelStyle, closeOnRelease, projectsSync, language },
+        changelogProvider, changelogBaseUrl, codeReviewCoderabbit, intent, mode: "full", semverAuto, appRelease, labelStyle, closeOnRelease, projectsSync, language, excludedWorkflows },
     })), { version, versionCode });
 
   // 2. README 버전 섹션
@@ -86,6 +88,7 @@ export function runFull(context, tempDir, targetRoot = ".", hooks = {}) {
     { enabled: codeReviewCoderabbit });
   step("ensure-gitignore", () => ensureGitignore(targetRoot));
   step("copy-setup-guide", () => copySetupGuide(tempDir, targetRoot));
+  step("install-agent-guide", () => installAgentGuide(targetRoot, templateVersion)); // agent 가 옵션을 확인하는 법 안내
 
   // 상태 라벨 표기(#776) — 템플릿 원본은 영문이라, 한글 레포는 복사가 끝난 뒤 이름만 되돌린다.
   step("apply-label-style", () => applyLabelStyle(targetRoot, labelStyle), { labelStyle });

package/src/commands/interactive.js

@@ -137,11 +137,13 @@ export async function runInteractive(baseCtx, { cwd = process.cwd(), source = {
     let deployBranchCreated = null; // #493 — 마법사가 직접 생성했는지 (가이드 기록용)
     let intent = existing?.options?.intent ?? null; // #485 프로젝트 성격
     // semver 자동 승격(#546) — 질문하지 않는다(#485 질문 부담 축소 방향 유지).
-    // 저장값이 있으면 보존, 없으면 신규 통합만 ON. 기존 레포는 업데이트만으로 버전이 튀지 않는다.
-    const semverAuto = existing?.options?.semverAuto ?? (existing ? false : true);
+    // 저장값(명시적 false 포함)은 보존하고, 키가 없으면 기존 레포도 ON. 켜진 사실은 완료 화면이 알린다.
+    const semverAuto = existing?.options?.semverAuto ?? true;
+    const semverAutoNewlyOn = !!existing && existing?.options?.semverAuto == null;
     const appRelease = existing?.options?.appRelease ?? null; // #553 저장값 보존 (묻지 않음)
     // 상태 라벨 표기(#776): 저장값 > (신규 en / 기존 ko). 기존 한글 레포에는 영문 전환을 한 번 제안한다(아래).
     const closeOnRelease = existing?.options?.closeOnRelease ?? (existing ? null : true); // #771 묻지 않는다
+    const excludedWorkflows = existing?.options?.excludedWorkflows ?? null; // #810 저장값 보존
     // Projects 보드 동기화(#716): 묻지 않는다. 저장값 > 이미 설치돼 있으면 유지 > 신규는 제외 (index.js 와 같은 규칙).
     const projectsSync = existing?.options?.projectsSync
       ?? existsSync(join(cwd, ".github/workflows/PROJECT-COMMON-PROJECTS-SYNC-MANAGER.yaml"));
@@ -328,7 +330,7 @@ export async function runInteractive(baseCtx, { cwd = process.cwd(), source = {
     const { now, today } = clock || utcNow();
     const ctx = createContext({
       mode, force: true, types, version, versionCode, branch, paths, deployTarget, publishTargets, includeSecretBackup,
-      codeReviewCoderabbit, changelogProvider, changelogBaseUrl, deployBranch, intent, semverAuto, appRelease, labelStyle, closeOnRelease, projectsSync, language,
+      codeReviewCoderabbit, changelogProvider, changelogBaseUrl, deployBranch, intent, semverAuto, appRelease, labelStyle, closeOnRelease, projectsSync, language, excludedWorkflows,
       repoName, templateVersion, resolvers, envValues, envUseDefaults, now, today,
       // #502 — version 모드가 기존 full 기록을 강등하지 않도록 (full이 우세)
       recordMode: existing?.templateMode === "full" ? "full" : "version",
@@ -423,7 +425,7 @@ export async function runInteractive(baseCtx, { cwd = process.cwd(), source = {
       migrationGuidePath = appendGuideEntry(cwd, {
         now, mode, types, repoName,
         templateFrom: existing?.templateVersion || "", templateTo: templateVersion,
-        options: { deploy: deployTarget, publish: publishTargets, secretBackup: includeSecretBackup, coderabbit: codeReviewCoderabbit, changelogProvider, intent, semverAuto , appRelease, labelStyle, closeOnRelease, projectsSync, language },
+        options: { deploy: deployTarget, publish: publishTargets, secretBackup: includeSecretBackup, coderabbit: codeReviewCoderabbit, changelogProvider, intent, semverAuto , appRelease, labelStyle, closeOnRelease, projectsSync, language, excludedWorkflows },
         branches: { defaultBranch: branch, deployBranch, ready: deployBranchReady, created: deployBranchCreated },
         breaking: breakingReport, migrations: migrationsResult, orphans: orphanReport,
         events: trace.events, counters: { skipped: result?.workflows?.skipped ?? 0 },
@@ -437,6 +439,9 @@ export async function runInteractive(baseCtx, { cwd = process.cwd(), source = {
       counters: { workflows: result?.workflows?.copied ?? 0, workflowFiles: result?.workflows?.copiedFiles ?? [], utilModules: 0 },
       skippedConflicts: result?.workflows?.skippedConflicts ?? [],   // #654 병합 안내
       replacedBak: result?.workflows?.replacedBak ?? [],             // #673 기준점 없이 교체한 파일 안내
+      legacyLeftover: migrationsResult?.confirmPending ?? [],         // #809 신·구 세대 동시 실행 안내
+      notInstalled: result?.workflows?.notInstalled ?? [],            // #810 깔지 않은 워크플로우 안내
+      semverAutoNewlyOn,
       verification: result?.verification,      // #549 설치 검증 결과
       aiPrSummary, codeReviewCoderabbit,       // #569 — 고른 것만 안내
       logDir: files ? MIGRATION_DIR : null,    // #561 기록 위치 안내

package/src/commands/version.js

@@ -5,7 +5,8 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { writeText } from "../core/fsutil.js";
 import { PATHS } from "../core/paths.js";
-import { buildVersionYml, mergeDeployValues } from "../core/version-yml.js";
+import { installAgentGuide } from "../core/agent-guide.js";
+import { buildVersionYml, mergeDeployValues, resolveUpdatedBy } from "../core/version-yml.js";
 import { markerForType } from "../core/detect.js";
 import { addVersionSectionToReadme } from "../core/copy/readme.js";
 import { applyLabelStyle } from "../core/label-style.js";
@@ -16,7 +17,7 @@ export function runVersion(context, tempDir, targetRoot = ".") {
   const { version, types = [], paths = new Map(), branch = "main", versionCode = 1,
     now, today, templateVersion = "unknown", deployTarget = "docker-ssh", publishTargets = [], includeSecretBackup = false,
     changelogProvider = "commit", changelogBaseUrl = "", codeReviewCoderabbit = true,
-    deployBranch = "", recordMode = "version", semverAuto = true , appRelease = null, labelStyle = "en", closeOnRelease = null, projectsSync = null, language = null } = context;
+    deployBranch = "", recordMode = "version", semverAuto = true , appRelease = null, labelStyle = "en", closeOnRelease = null, projectsSync = null, language = null, excludedWorkflows = null } = context;
 
   const pathMarkers = new Map();
   for (const [t] of paths) pathMarkers.set(t, markerForType(t));
@@ -29,10 +30,11 @@ export function runVersion(context, tempDir, targetRoot = ".") {
     buildVersionYml({
       version, types, paths, pathMarkers, branch, deployBranch, versionCode, now, today,
       deployValues,
+      updatedBy: resolveUpdatedBy(existsSync(vyFile) ? readFileSync(vyFile, "utf8") : "", targetRoot), // #811
       // mode(#502): version 모드가 기존 full 통합 기록을 "version"으로 강등하지 않도록
       // 호출부가 recordMode로 기존 값을 넘긴다 (full이 우세 — 업데이트 재실행 범위 축소 방지).
       templateOptions: { templateVersion, deployTarget, publishTargets, includeSecretBackup, optionsDate: today,
-        changelogProvider, changelogBaseUrl, codeReviewCoderabbit, mode: recordMode, semverAuto, appRelease, labelStyle, closeOnRelease, projectsSync, language },
+        changelogProvider, changelogBaseUrl, codeReviewCoderabbit, mode: recordMode, semverAuto, appRelease, labelStyle, closeOnRelease, projectsSync, language, excludedWorkflows },
     }));
   addVersionSectionToReadme(version, targetRoot);
   copyScripts(tempDir, targetRoot);
@@ -40,4 +42,5 @@ export function runVersion(context, tempDir, targetRoot = ".") {
   applyLabelStyle(targetRoot, labelStyle); // #776
   ensureGitignore(targetRoot);
   copySetupGuide(tempDir, targetRoot);
+  installAgentGuide(targetRoot, templateVersion);
 }

package/src/commands/workflows.js

@@ -9,6 +9,7 @@ import { applyLabelStyle } from "../core/label-style.js";
 import { copyScripts, copyConfigFolder, copySetupGuide } from "../core/copy/simple.js";
 import { copyUtilModules } from "../core/copy/util.js";
 import { convertLegacySingularType, mergeDeployValues } from "../core/version-yml.js";
+import { installAgentGuide } from "../core/agent-guide.js";
 import { verifyInstall } from "../core/verify.js";
 
 export function runWorkflows(context, tempDir, targetRoot = ".", hooks = {}) {
@@ -35,6 +36,7 @@ export function runWorkflows(context, tempDir, targetRoot = ".", hooks = {}) {
   applyLabelStyle(targetRoot, labelStyle); // #776 — 워크플로우(QA 봇)와 라벨 정의를 같은 표기로 맞춘다
   for (const t of types) copyUtilModules(tempDir, t, { force }, targetRoot);
   copySetupGuide(tempDir, targetRoot);
+  installAgentGuide(targetRoot, context.templateVersion);
 
   // 설치 후 검증 (#549) — 워크플로우만 설치하는 모드라 오히려 더 필요하다.
   const verification = verifyInstall(targetRoot);

package/src/context.js

@@ -27,10 +27,11 @@ export function createContext(overrides = {}) {
     codeReviewCoderabbit: null,
     deployBranch: "",        // 릴리스 PR head 브랜치 (#456). 빈 값=metadata.deploy_branch 미출력
     intent: null,            // 프로젝트 성격 (#485 — app/library/both/none/manual). null=미설정(역추론)
-    semverAuto: null,        // semver 자동 승격 (#546). null=미설정(신규 통합 true / 기존 레포 false)
+    semverAuto: null,        // semver 자동 승격 (#546). null=미설정 → 신규·기존 모두 true (#814). 명시적 false 만 끈다
     closeOnRelease: null,    // 릴리스 시 완료 이슈 닫기 (#771). null=미설정(신규 true / 기존 레포 키 없음)
     language: null,          // 레포 문구 언어 (#769). null=미설정(신규 en / 기존 레포 ko)
     labelStyle: null,        // 상태 라벨 표기 (#776). null=미설정(신규 en / 기존 레포 ko)
+    excludedWorkflows: null, // 설치하지 않을 워크플로우 파일명 (#810). null=없음
     appRelease: null,        // 앱 심사 배포 레포인가 (#553). null=미설정(키 기록 안 함)
     templateVersion: "",
     tempDir: "",

package/src/core/agent-guide.js

@@ -0,0 +1,44 @@
+// 사용자 레포에 설치하는 AI agent 안내문 (.github/.projectops/AGENT-GUIDE.md).
+//
+// 왜 파일인가: 이 레포의 AGENTS.md 는 템플릿 전용이라 사용자 프로젝트로 가지 않는다. 그래서 projectops 가
+// 깔린 레포에서 일하는 agent 는 "이 레포가 무엇으로 관리되는지, 옵션을 어디서 확인하는지"를 알 길이 없었다.
+// 레포 루트의 AGENTS.md·CLAUDE.md 는 사용자 것이라 건드리지 않고, 폴더 안에 두고 한 줄 포인터만 안내한다.
+//
+// 내용에 옵션 표를 박지 않는다 — 박으면 곧 낡는다. 표는 항상 `npx projectops --mode options --json` 이 정본이다.
+import { join } from "node:path";
+import { writeText } from "./fsutil.js";
+
+export const AGENT_GUIDE_PATH = ".github/.projectops/AGENT-GUIDE.md";
+
+export function agentGuideText(templateVersion = "") {
+  return `# projectops — guide for AI agents
+
+This repository is managed with [projectops](https://github.com/Cassiiopeia/projectops)${templateVersion ? ` (installed template ${templateVersion})` : ""}.
+GitHub Actions workflows in \`.github/workflows/PROJECT-*\` handle versioning, release notes, CI/CD and issue automation.
+This file is generated by the installer and overwritten on update. Do not edit it.
+
+## Ask the tool, do not guess
+
+\`\`\`bash
+npx projectops --mode options --json   # every CLI flag and every version.yml key, with allowed values and defaults
+npx projectops --mode doctor           # read-only diagnosis of this install and the repository settings
+\`\`\`
+
+Both are read-only and need no network.
+
+## Rules
+
+- Settings live in \`version.yml\` under \`metadata.template.options\`. The options table says which keys are safe to edit by hand.
+- \`version\` in \`version.yml\` is the single source of the project version. Workflows bump it on release; do not bump it by hand unless asked.
+- Commit titles decide the release bump when \`semver_auto\` is on: \`feat:\` = minor, \`feat!:\` = major, anything else = patch.
+- Running the installer again updates workflows. Files you changed are kept (a copy of the new version is saved in \`.github/.projectops/incoming/\`). Files you deleted are not restored.
+- To stop a template workflow from ever being installed, list its file name in \`options.excluded_workflows\`.
+- Run the installer from an agent or CI only with an explicit mode and \`--force\`, e.g. \`npx projectops --mode workflows --force\`. Without \`--force\` it asks questions and blocks.
+- Do not edit \`.github/.projectops/logs\`, \`baseline.json\` or \`incoming/\`. They are diagnostics for the next update.
+`;
+}
+
+export function installAgentGuide(targetRoot = ".", templateVersion = "") {
+  writeText(join(targetRoot, AGENT_GUIDE_PATH), agentGuideText(templateVersion));
+  return AGENT_GUIDE_PATH;
+}

package/src/core/constants.js

@@ -0,0 +1,28 @@
+// 여러 파일이 함께 써야 하는 값 목록의 정본.
+//
+// 왜 한 곳인가: deploy·publish 목록이 CLI 인자 검사(args.js), 마법사 질문(options-ask.js),
+// 복사 엔진(copy/workflows.js), version.yml 파서(version-yml.js), 옵션 표(options-schema.js)
+// 다섯 곳에 따로 적혀 있었다. 하나만 고치면 "CLI 는 받는데 파서가 버린다" 같은 조용한 불일치가 생긴다.
+// 값을 추가할 때는 여기 한 줄만 고치고, 그 값에 해당하는 워크플로우 폴더를 만든다
+// (deploy: project-types/common/deploy/<값>/ · publish: project-types/<type>/publish/<값>/).
+//
+// 이 파일은 아무것도 import 하지 않는다 — 어디서 불러도 순환 import 가 생기지 않게.
+// 레포 문구 언어 목록은 repo-language.js 의 REPO_LANGUAGES 가 정본이다 (번역 파일과 같이 검사된다).
+
+/** 실행물을 어디에 배포하나 — 택1 (#439) */
+export const DEPLOY_TARGETS = Object.freeze(["docker-ssh", "vercel", "none"]);
+
+/** 라이브러리를 어느 레지스트리에 내나 — 0..n (#439) */
+export const PUBLISH_TARGETS = Object.freeze(["nexus", "npm", "github-packages"]);
+
+/** 프로젝트 성격 — deploy/publish 질문을 유도한다 (#485) */
+export const INTENT_VALUES = Object.freeze(["app", "library", "both", "none", "manual"]);
+
+/** 상태 라벨 표기 — en: `status: todo`, ko: 기존 한글 `작업전` (#776) */
+export const LABEL_STYLES = Object.freeze(["en", "ko"]);
+
+/**
+ * 릴리스 노트 생성기 (#455, #566). 기본값은 commit — 외부 의존이 없어 어디서나 결과가 나온다.
+ * 실제 구현은 .github/scripts/changelog_providers/ 에 있고, 그쪽 목록과의 정합은 테스트가 본다.
+ */
+export const CHANGELOG_PROVIDERS = Object.freeze(["copilot", "coderabbit", "openai", "gemini", "claude", "groq", "mistral", "ollama", "commit"]);

package/src/core/copy/simple.js

@@ -1,6 +1,6 @@
 // 단순 복사 함수 (무조건 덮어쓰기류) — .sh copy_scripts/config/issue/discussion/setup_guide 등가.
 // 실측: template_integrator.sh 3818, 3845, 3872, 3895, 4114.
-import { join } from "node:path";
+import { join, basename } from "node:path";
 import { chmodSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { PATHS } from "../paths.js";
 import { exists, copyFileSync, copyDirSync } from "../fsutil.js";
@@ -97,7 +97,8 @@ export function stripIssueTemplateAssignees(targetRoot = ".") {
 // .github/ISSUE_TEMPLATE/ 전체 + PULL_REQUEST_TEMPLATE.md 덮어쓰기.
 export function copyIssueTemplates(tempDir, targetRoot = ".") {
   const srcIssue = join(tempDir, ".github", "ISSUE_TEMPLATE");
-  if (exists(srcIssue)) copyDirSync(srcIssue, join(targetRoot, ".github", "ISSUE_TEMPLATE"));
+  // `projectops-` 로 시작하는 파일은 이 저장소(projectops 자체)의 이슈 양식이라 사용자 레포로 복사하지 않는다 (#797).
+  if (exists(srcIssue)) copyDirSync(srcIssue, join(targetRoot, ".github", "ISSUE_TEMPLATE"), { filter: (src) => !basename(src).startsWith("projectops-") });
   const srcPr = join(tempDir, ".github", "PULL_REQUEST_TEMPLATE.md");
   if (exists(srcPr)) copyFileSync(srcPr, join(targetRoot, ".github", "PULL_REQUEST_TEMPLATE.md"));
 }