create-filegrc 0.2.0 → 0.3.1

package/src/index.js

@@ -4,32 +4,43 @@ import { basename, dirname, extname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 import { createInterface } from "node:readline/promises";
-import { baselineRecordPaths, writeBaselineRecords } from "./defaults.js";
+import { baselineRecordFiles, baselineRecordPaths, writeBaselineRecords } from "./defaults.js";
 
 const execute = promisify(execFile);
 const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
 const textExtensions = new Set(["", ".json", ".md", ".txt", ".yml", ".yaml", ".gitignore"]);
+const STARTER_PROFILES = new Set(["foundation", "security"]);
+const SECURITY_TEMPLATE_COLLECTIONS = new Set(["documents", "policies", "training"]);
 
-export async function createFileGRC(options = {}) {
+export async function createFilegrc(options = {}) {
   const parameterConfig = JSON.parse(await readFile(join(packageRoot, "template-parameters.json"), "utf8"));
   const target = resolve(options.target ?? "filegrc-program");
+  const starter = normalizeStarterProfile(options.starter);
+  if (options.setup && options.install === false) {
+    throw new Error("Combined service setup requires installation. Remove --no-install or run filegrc setup after npm install.");
+  }
+  validateCombinedSetup(options.setup);
   await assertWritableTarget(target, Boolean(options.force));
-  if (options.force) await assertNoTemplateCollisions(target);
+  if (options.force) await assertNoTemplateCollisions(target, starter);
 
   const prompted = await resolvePromptValues(parameterConfig.parameters, options);
-  const engineVersion = await resolveFileGRCVersion(options.filegrcVersion);
+  const engine = await resolveEngine(options);
+  const starterText = starterTemplateText(starter, prompted.company_name);
   const values = {
     ...prompted,
     effective_date: options.effectiveDate ?? new Date().toISOString().slice(0, 10),
     project_name: normalizePackageName(basename(target)),
-    filegrc_version: engineVersion,
-    filegrc_version_range: `^${engineVersion}`
+    filegrc_version: engine.version,
+    filegrc_version_range: engine.dependency,
+    ...starterText
   };
 
   await mkdir(target, { recursive: true });
-  await copyTemplate(target);
-  await renderTemplate(target, parameterConfig, values);
-  await writeBaselineRecords(target, values.effective_date);
+  await copyTemplate(target, starter);
+  await renderTemplate(target, parameterConfig, values, starter);
+  await writeBaselineRecords(target, values.effective_date, starter);
+  await applyStarterScope(target, starter, values.effective_date);
+  const initialResourceCounts = await summarizeResources(target);
 
   const installed = options.install !== false;
   if (installed) {
@@ -39,16 +50,34 @@ export async function createFileGRC(options = {}) {
   }
   const joinedExistingWorktree = await isInsideGitWorktree(target);
   if (!joinedExistingWorktree) await run("git", ["init"], target);
+  const setup = options.setup ? await runCombinedSetup(target, options.setup) : null;
+  const resourceCounts = setup ? await summarizeResources(target) : initialResourceCounts;
   return {
     target,
     values,
-    engineVersion,
+    starter,
+    engineVersion: engine.version,
+    engineSource: engine.localPath ? "local" : "registry",
+    enginePackage: engine.localPath || null,
+    dependency: engine.dependency,
+    stages: starterStages(starter, initialResourceCounts),
+    resourceCounts,
+    setup,
     install: installed ? "installed" : "skipped",
     gitMode: joinedExistingWorktree ? "existing-worktree" : "initialized"
   };
 }
 
-export async function resolveFileGRCVersion(explicitVersion) {
+export function normalizeStarterProfile(value = "security") {
+  const profile = String(value || "security").trim().toLowerCase();
+  const normalized = profile === "empty" ? "foundation" : profile === "soc2-security" ? "security" : profile;
+  if (!STARTER_PROFILES.has(normalized)) {
+    throw new Error(`Starter profile must be one of ${[...STARTER_PROFILES].join(", ")}.`);
+  }
+  return normalized;
+}
+
+export async function resolveFilegrcVersion(explicitVersion) {
   if (explicitVersion) return cleanVersion(explicitVersion);
   try {
     const { stdout } = await execute("npm", ["view", "filegrc", "version", "--json"], {
@@ -63,11 +92,35 @@ export async function resolveFileGRCVersion(explicitVersion) {
   }
 }
 
+async function resolveEngine(options) {
+  if (options.filegrcVersion && options.filegrcPackage) {
+    throw new Error("Use either filegrcVersion or filegrcPackage, not both.");
+  }
+  if (!options.filegrcPackage) {
+    const version = await resolveFilegrcVersion(options.filegrcVersion);
+    return { version, dependency: `^${version}`, localPath: null };
+  }
+  const localPath = resolve(String(options.filegrcPackage));
+  let packageJson;
+  try {
+    packageJson = JSON.parse(await readFile(join(localPath, "package.json"), "utf8"));
+  } catch (error) {
+    throw new Error(`Could not read a local filegrc package at ${localPath}: ${error.message}`);
+  }
+  if (packageJson.name !== "filegrc") {
+    throw new Error(`Local package at ${localPath} is named "${packageJson.name || ""}", expected "filegrc".`);
+  }
+  const version = cleanVersion(packageJson.version);
+  return { version, dependency: `file:${localPath.replaceAll("\\", "/")}`, localPath };
+}
+
 async function resolvePromptValues(parameters, options) {
   const mapped = {
     company_name: options.companyName,
     policy_owner_name: options.policyOwnerName,
-    security_contact_email: options.securityContactEmail
+    policy_owner_email: options.policyOwnerEmail,
+    security_contact_email: options.securityContactEmail,
+    timezone: options.timezone
   };
   if (options.yes) {
     mapped.company_name ??= "Example Company";
@@ -77,21 +130,29 @@ async function resolvePromptValues(parameters, options) {
   for (const key of Object.keys(mapped)) {
     if (mapped[key] !== undefined && mapped[key] !== null) mapped[key] = String(mapped[key]).trim();
   }
-  const missing = parameters.filter(({ key, required }) => required && !mapped[key]);
-  if (missing.length) {
-    if (!process.stdin.isTTY || !process.stdout.isTTY) {
-      throw new Error(`Missing required values: ${missing.map(({ key }) => key).join(", ")}`);
-    }
+  if (process.stdin.isTTY && process.stdout.isTTY) {
     const prompt = createInterface({ input: process.stdin, output: process.stdout });
     try {
-      for (const parameter of missing) {
+      for (const parameter of parameters.filter(({ required, key }) => required && !mapped[key])) {
+        const defaultValue = parameterDefault(parameter, mapped);
+        const suffix = defaultValue ? ` [${defaultValue}]` : "";
         let value = "";
-        while (!value) value = (await prompt.question(`${parameter.prompt}: `)).trim();
+        while (!value) {
+          value = (await prompt.question(`${parameter.prompt}${suffix}: `)).trim() || defaultValue;
+        }
         mapped[parameter.key] = value;
       }
     } finally {
       prompt.close();
     }
+  } else {
+    for (const parameter of parameters.filter(({ required, key }) => required && !mapped[key])) {
+      mapped[parameter.key] = parameterDefault(parameter, mapped);
+    }
+  }
+  const missing = parameters.filter(({ key, required }) => required && !mapped[key]);
+  if (missing.length) {
+    throw new Error(`Missing required values: ${missing.map(({ key }) => key).join(", ")}`);
   }
   for (const key of ["company_name", "policy_owner_name"]) {
     if (/[\u0000-\u001f\u007f]/.test(mapped[key])) {
@@ -102,12 +163,39 @@ async function resolvePromptValues(parameters, options) {
       throw new Error(`${key} cannot contain template token syntax.`);
     }
   }
-  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(mapped.security_contact_email)) {
-    throw new Error("Security contact email must be a valid email address.");
+  for (const [key, label] of [
+    ["policy_owner_email", "Policy owner email"],
+    ["security_contact_email", "Security contact email"]
+  ]) {
+    if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(mapped[key])) {
+      throw new Error(`${label} must be a valid email address.`);
+    }
   }
+  if (!isTimezone(mapped.timezone)) throw new Error("Program timezone must be a valid IANA time zone.");
   return mapped;
 }
 
+function parameterDefault(parameter, mapped) {
+  if (parameter.defaultFrom) return mapped[parameter.defaultFrom] || "";
+  if (parameter.defaultSource === "local-timezone") return localTimezone();
+  return "";
+}
+
+function localTimezone() {
+  const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+  return isTimezone(timezone) ? timezone : "UTC";
+}
+
+function isTimezone(value) {
+  if (!value) return false;
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: value }).format();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 async function assertWritableTarget(target, force) {
   try {
     if ((await lstat(target)).isSymbolicLink()) {
@@ -122,9 +210,9 @@ async function assertWritableTarget(target, force) {
   }
 }
 
-async function assertNoTemplateCollisions(target) {
+async function assertNoTemplateCollisions(target, starter) {
   const collisions = [];
-  for (const destinationPath of [...await templateDestinationPaths(), ...baselineRecordPaths()]) {
+  for (const destinationPath of [...await templateDestinationPaths(starter), ...baselineRecordPaths(starter)]) {
     await assertNoSymlinkComponents(target, destinationPath);
     try {
       await lstat(join(target, destinationPath));
@@ -153,20 +241,22 @@ async function assertNoSymlinkComponents(target, relativePath) {
   }
 }
 
-async function renderTemplate(target, parameterConfig, values) {
+async function renderTemplate(target, parameterConfig, values, starter) {
   const declared = new Set([
     ...parameterConfig.parameters.map(({ key }) => key),
     ...parameterConfig.generated.map(({ key }) => key)
   ]);
-  const files = (await templateDestinationPaths()).map((path) => join(target, path));
+  const files = (await templateDestinationPaths(starter)).map((path) => join(target, path));
   for (const path of files) {
     if (!textExtensions.has(extname(path)) && basename(path) !== ".gitignore") continue;
     let source = await readFile(path, "utf8");
     const jsonFile = extname(path) === ".json";
-    source = source.replace(/\{\{([a-z0-9_]+)\}\}/g, (match, token) => {
+    source = source.replace(/\{\{([a-z0-9_]+)\}\}(\.)?/g, (match, token, sentencePeriod = "") => {
       if (!declared.has(token)) throw new Error(`Unknown template token "{{${token}}}" in ${path}`);
       if (values[token] === undefined) throw new Error(`No value resolved for template token "{{${token}}}"`);
-      return jsonFile ? jsonStringContents(values[token]) : String(values[token]);
+      const value = jsonFile ? jsonStringContents(values[token]) : String(values[token]);
+      const punctuation = !jsonFile && sentencePeriod && /[.!?]$/u.test(value) ? "" : sentencePeriod;
+      return value + punctuation;
     });
     const unresolved = /\{\{([a-z0-9_]+)\}\}/.exec(source);
     if (unresolved) throw new Error(`Unresolved template token "{{${unresolved[1]}}}" in ${path}`);
@@ -174,20 +264,22 @@ async function renderTemplate(target, parameterConfig, values) {
   }
 }
 
-async function templateDestinationPaths() {
+async function templateDestinationPaths(starter = "security") {
   const template = join(packageRoot, "template");
   return (await collectFiles(template)).flatMap((source) => {
     const templatePath = relative(template, source);
+    if (!includeTemplatePath(templatePath, starter)) return [];
     if (templatePath === "README.md") return [];
     if (templatePath === "WORKSPACE.md") return ["README.md"];
     return [templatePath === "gitignore" ? ".gitignore" : templatePath];
   });
 }
 
-async function copyTemplate(target) {
+async function copyTemplate(target, starter = "security") {
   const template = join(packageRoot, "template");
   for (const source of await collectFiles(template)) {
     const templatePath = relative(template, source);
+    if (!includeTemplatePath(templatePath, starter)) continue;
     if (templatePath === "README.md") continue;
     const destinationPath = templatePath === "WORKSPACE.md"
       ? "README.md"
@@ -203,6 +295,13 @@ async function copyTemplate(target) {
   }
 }
 
+function includeTemplatePath(templatePath, starter) {
+  if (starter === "security") return true;
+  const segments = templatePath.split(/[\\/]/);
+  if (segments[0] !== "data" || !SECURITY_TEMPLATE_COLLECTIONS.has(segments[1])) return true;
+  return segments.at(-1) === "AGENTS.md";
+}
+
 async function collectFiles(directory) {
   const result = [];
   for (const item of await readdir(directory, { withFileTypes: true })) {
@@ -213,16 +312,150 @@ async function collectFiles(directory) {
   return result;
 }
 
+async function summarizeResources(target) {
+  const counts = {};
+  let total = 0;
+  for (const path of await collectFiles(join(target, "data"))) {
+    if (extname(path) !== ".json") continue;
+    const record = JSON.parse(await readFile(path, "utf8"));
+    if (!record?.id || !record?.type || !record?.schemaVersion) continue;
+    total += 1;
+    counts[record.type] = (counts[record.type] || 0) + 1;
+  }
+  return { total, byType: counts };
+}
+
+async function applyStarterScope(target, starter, effectiveDate) {
+  if (starter !== "security") return;
+  const records = baselineRecordFiles(effectiveDate, starter).map(({ record }) => record);
+  const workspacePath = join(target, "data", "workspace.json");
+  const workspace = JSON.parse(await readFile(workspacePath, "utf8"));
+  const ids = (type) => records.filter((record) => record.type === type).map((record) => record.id);
+  await writeFile(workspacePath, `${JSON.stringify({
+    ...workspace,
+    frameworkIds: ids("framework"),
+    requirementIds: ids("requirement"),
+    controlIds: ids("control")
+  }, null, 2)}\n`, "utf8");
+}
+
+function starterStages(starter, counts) {
+  const foundationTypes = new Set(["workspace", "renderer-settings", "person", "team", "system"]);
+  const foundation = Object.entries(counts.byType)
+    .filter(([type]) => foundationTypes.has(type))
+    .reduce((total, [, count]) => total + count, 0);
+  return [
+    { id: "foundation", status: "created", records: foundation },
+    {
+      id: "soc2-security",
+      status: starter === "security" ? "created" : "skipped",
+      records: starter === "security" ? counts.total - foundation : 0
+    }
+  ];
+}
+
+function starterTemplateText(starter, companyName) {
+  if (starter === "foundation") {
+    return {
+      program_title: `${companyName} GRC Program`,
+      program_description: "Governance, risk, and compliance workspace without a preselected framework.",
+      program_summary: `This private workspace holds ${companyName}'s governance, risk, compliance, and audit-evidence records. JSON under \`data/\` stores structured records, Markdown stores long-form work, and Git records reviewed changes.`,
+      agent_title: "filegrc Workspace Instructions",
+      agent_purpose: `This repository is ${companyName}’s foundation filegrc workspace. Engineers and agents maintain the source records under \`data/\`. The \`filegrc\` package validates, searches, edits, and renders those files. No framework or assurance program has been selected yet.`,
+      starter_baseline: `## Foundation baseline
+
+The generated workspace starts with five structural records:
+
+- Workspace and renderer settings
+- The initial active owner
+- An inactive security and risk oversight team that still needs an independent chair
+- The filegrc Git repository as a governance system of record
+- A default 5x5 risk method and Public, Internal, Confidential, and Restricted data classifications
+
+This profile does not include framework requirements, policies, governed documents, training, controls, obligations, or audit-management templates. Add and review those records for the selected framework before treating Program Readiness or Audit Readiness as meaningful. Do not infer that an absent control, policy, or schedule is unnecessary.`,
+      audit_preparation_guidance: "The foundation profile does not include the local SOC 2 management-document templates used by `prepare-audit`. Add reviewed templates and program scope before initializing audit work. Audit preparation must not invent missing policy, control, or evidence facts.",
+      starter_setup: `## Start the program
+
+This foundation profile contains the workspace, initial owner, oversight team, renderer settings, and filegrc system of record. It does not select a framework or create proposed policies, controls, obligations, or evidence.
+
+1. Run \`npx filegrc setup\` for guided service and goal setup, or use browser onboarding.
+2. Use \`npx filegrc guide --json\` before creating framework requirements, policies, controls, obligations, and evidence sources.
+3. Run \`npx filegrc validate\`, review the Git diff, and commit each reviewed program layer.`
+    };
+  }
+  return {
+    program_title: `${companyName} SOC 2 Program`,
+    program_description: "SOC 2 Security program based on the AICPA Trust Services Criteria.",
+    program_summary: `This private workspace holds ${companyName}'s SOC 2 program records and audit evidence. JSON under \`data/\` stores structured records, Markdown stores long-form work, and Git records reviewed changes.`,
+    agent_title: "filegrc SOC 2 Workspace Instructions",
+    agent_purpose: `This repository is ${companyName}’s filegrc workspace for its SOC 2 program. Engineers and agents maintain the source records under \`data/\`. The \`filegrc\` package validates, searches, edits, and renders those files.`,
+    starter_baseline: `## Starter baseline
+
+The generated workspace starts with the SOC 2 Security category:
+
+- Active framework records for the 2017 Trust Services Criteria with revised points of focus (2022) and the 2018 SOC 2 Description Criteria with revised implementation guidance (2022)
+- The 33 Common Criteria reference IDs from CC1.1 through CC9.2, without the licensed criteria text
+- The nine Description Criteria reference IDs from DC1 through DC9, without the licensed criteria text
+- Planned controls mapped to those references and the included policies
+- A security and risk oversight team chaired by an independent reviewer who may be internal or external
+- Recurring obligations for the reviews, scans, tests, training, and meetings required by the included policies
+- A default 5x5 risk method and Public, Internal, Confidential, and Restricted data classifications
+
+Treat every planned control as a proposal until its owner, actual procedure in Record Markdown, system scope, cadence, authoritative evidence sources, implementation date, and mappings match actual practice. For a control linked to filegrc obligations, every non-retired Work Queue schedule must be enabled and its governing policies effective. Marking the control implemented starts eligible schedules. Do not mark a control implemented because a policy describes it. Add Availability, Processing Integrity, Confidentiality, or Privacy criteria only when they are in scope.
+
+The recurring obligations mirror the fixed cadences in the starter policies. They remain proposals until every governing policy is active and effective and, when they name controls, at least one linked control is implemented. Update the policy, control, and obligation together when an approved cadence changes. Create separate completion records, such as meetings, reviews, scans, tests, exercises, and attestations, for each period.`,
+    audit_preparation_guidance: "Preparation creates a separate system description, management assertion, and management representation document for the engagement from the local starter templates. Type 2 preparation also creates a period completeness statement and one `audit-population` record for each standard population. It is safe to run again and does not approve documents, mark controls implemented, or create evidence. Do not reuse one completed management document across engagements.",
+    starter_setup: `## Finish initial setup
+
+The starter policies, controls, and obligations are proposals. They do not state that ${companyName} operates the described controls.
+
+1. Run \`npx filegrc setup\` for guided service and goal setup, or use browser onboarding. Then finish Step 1 by adding the real reviewers and operators, finishing the oversight team, and confirming applicable criteria, commitments, material vendors, and in-scope systems.
+2. Review the starter policies, appoint a reviewer who is separate from the policy owner, and activate only the policies that match current practice. The reviewer will usually be another person in the organization, but may be external.
+3. Review the starter control set, implement each applicable control with its actual procedure, scope, cadence, evidence sources, and implementation date, and confirm any linked Work Queue schedules are enabled. Marking a control implemented starts eligible schedules. Then record any complementary customer or subservice controls.
+4. Preview External Evidence drafts with \`npx filegrc evidence-test-drafts --preview --json\`. Create them only after confirming applicable controls and authoritative source systems.
+5. Run \`npx filegrc program-readiness --require-ready\`, record the management candidate period start when reliable evidence collection begins, maintain risk assessments and risks, update controls when needed, use Work Queue for scheduled work, and trigger Policy Events when changes create required actions.
+6. Engage a CPA firm, record the separate firm-agreed period in an audit record, review filegrc Evidence and External Evidence, and prepare fieldwork.`
+  };
+}
+
+function validateCombinedSetup(setup) {
+  if (!setup) return;
+  if (Array.isArray(setup) || typeof setup !== "object") throw new Error("setup must be a JSON object.");
+  const required = ["serviceName", "boundary", "criticality", "dataClassification", "internetExposed"];
+  const missing = required.filter((name) => setup[name] === undefined || setup[name] === "");
+  if (missing.length) throw new Error(`Combined setup is missing: ${missing.join(", ")}.`);
+}
+
+async function runCombinedSetup(target, input) {
+  const setup = { programGoal: "none", ownerId: "person-policy-owner", ...input };
+  const args = [
+    join(target, "node_modules", "filegrc", "bin", "filegrc.js"),
+    "setup",
+    "--service-name", String(setup.serviceName),
+    "--boundary", String(setup.boundary),
+    "--owner", String(setup.ownerId),
+    "--criticality", String(setup.criticality),
+    "--classification", String(setup.dataClassification),
+    "--internet-exposed", String(setup.internetExposed),
+    "--program-goal", String(setup.programGoal),
+    "--summary",
+    "--json"
+  ];
+  if (setup.draft === true) args.push("--draft");
+  const result = await run(process.execPath, args, target);
+  return JSON.parse(result.stdout);
+}
+
 async function writeMinimalLockfile(target, name, versionRange) {
   const lock = {
     name,
-    version: "0.2.0",
+    version: "0.3.1",
     lockfileVersion: 3,
     requires: true,
     packages: {
       "": {
         name,
-        version: "0.2.0",
+        version: "0.3.1",
         dependencies: { filegrc: versionRange }
       }
     }
@@ -251,7 +484,7 @@ async function run(command, args, cwd) {
 function cleanVersion(value) {
   const version = String(value ?? "").trim().replace(/^v/, "");
   if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version)) {
-    throw new Error(`Could not resolve a valid FileGRC version from "${value}".`);
+    throw new Error(`Could not resolve a valid filegrc version from "${value}".`);
   }
   return version;
 }

package/template/AGENTS.md

@@ -1,8 +1,8 @@
-# FileGRC SOC 2 Workspace Instructions
+# {{agent_title}}
 
 ## Purpose
 
-This repository is {{company_name}}’s FileGRC workspace for its SOC 2 program. Engineers and agents maintain the source records under `data/`. The `filegrc` package validates, searches, edits, and renders those files.
+{{agent_purpose}}
 
 Using this repository does not establish compliance by itself. Records must match actual practice and evidence must prove that controls operated during the audit period.
 
@@ -15,7 +15,7 @@ npx filegrc guide --json
 npx filegrc program-path --json
 npx filegrc guide risk-assessment --json
 npx filegrc list person --json
-npx filegrc program-readiness --json
+npx filegrc program-readiness --summary --json
 ```
 
 `program-path` gives agents the same six-step order, exact page Instructions, Use, Policy Basis, commands, current state, and next actions shown in the renderer. The general guide lists every supported action and record type. A type guide repeats that page guidance and adds timing, required and conditional fields, current relationship candidates, JSON location, and Markdown slots.
@@ -46,7 +46,7 @@ Read `data/AGENTS.md` before changing records. More specific instructions inside
 - Let the local app generate IDs from each record’s name or title. When editing JSON directly, keep IDs globally unique, human-readable, and lowercase kebab-case.
 - Use ISO 8601 dates and RFC 3339 timestamps.
 - Store relationships as resource IDs.
-- Put policies, plans, charters, procedures, meeting minutes, training, assertions, narratives, templates, and audit responses in Markdown beside their JSON records. FileGRC derives the Markdown name, so records do not contain file paths.
+- Put policies, plans, charters, procedures, meeting minutes, training, assertions, narratives, templates, and audit responses in Markdown beside their JSON records. filegrc derives the Markdown name, so records do not contain file paths.
 - Put signed forms, screenshots, third-party reports, and immutable exports behind evidence records. These files may be PDF, image, CSV, or another fixed format.
 - Never fetch an external evidence reference automatically.
 - Do not store secrets, credentials, session data, or personal data that may need to be erased from Git history.
@@ -95,25 +95,11 @@ Headless agents get the same protection by exporting an edit payload with `fileg
 
 `data/renderer.json` stores committed renderer preferences. New workspaces set `showOnboarding` to `true`. Completing or skipping onboarding sets it to `false`; the app does not commit that change.
 
-Onboarding explains the file and Git workflow, the program path, policy obligations, and Policy Events before covering report types and the final audit stage. It then collects the initial service boundary, owner, business criticality, highest data classification, internet exposure, and optional program goal. It creates or updates a `system` record and stores the management goal and program scope on `workspace`. Selecting Type 1 or Type 2 does not create an audit engagement. Completing onboarding opens the Step 1 overview so the user can confirm the starter people and oversight team, criteria, commitments, vendors, and systems before approving policies.
+Onboarding explains the file and Git workflow, the program path, policy obligations, and Policy Events before covering report types and the final audit stage. It then collects the initial service boundary, owner, business criticality, highest data classification, internet exposure, and optional program goal. It creates or updates one `system` record and stores that selected system and the management goal on `workspace`. It does not select framework records, link controls to the service, or create evidence. Selecting Type 1 or Type 2 does not create an audit engagement. Completing onboarding opens the Step 1 overview so the user can add the real reviewers and operators, finish the oversight team, and confirm the criteria, commitments, vendors, and systems before approving policies.
 
 The renderer is optional. Agents may set `showOnboarding` to `false` and maintain all records headlessly. Restart onboarding from Repository when useful. Read-only builds never run it.
 
-## Starter baseline
-
-The generated workspace starts with the SOC 2 Security category:
-
-- Active framework records for the 2017 Trust Services Criteria with revised points of focus (2022) and the 2018 SOC 2 Description Criteria with revised implementation guidance (2022)
-- The 33 Common Criteria reference IDs from CC1.1 through CC9.2, without the licensed criteria text
-- The nine Description Criteria reference IDs from DC1 through DC9, without the licensed criteria text
-- Planned controls mapped to those references and the included policies
-- A security and risk oversight team chaired by an independent reviewer who may be internal or external
-- Recurring obligations for the reviews, scans, tests, training, and meetings required by the included policies
-- A default 5x5 risk method and Public, Internal, Confidential, and Restricted data classifications
-
-Treat every planned control as a proposal until its owner, actual procedure in Record Markdown, system scope, cadence, authoritative evidence sources, implementation date, and mappings match actual practice. For a control linked to FileGRC obligations, every non-retired Work Queue schedule must be enabled and its governing policies effective. Marking the control implemented starts eligible schedules. Do not mark a control implemented because a policy describes it. Add Availability, Processing Integrity, Confidentiality, or Privacy criteria only when they are in scope.
-
-The recurring obligations mirror the fixed cadences in the starter policies. They remain proposals until every governing policy is active and effective and, when they name controls, at least one linked control is implemented. Update the policy, control, and obligation together when an approved cadence changes. Create separate completion records, such as meetings, reviews, scans, tests, exercises, and attestations, for each period.
+{{starter_baseline}}
 
 ## Work Queue and Policy Events
 
@@ -141,7 +127,7 @@ npx filegrc trigger person-started --occurred-on 2026-07-25 --subject person-new
 npx filegrc trigger person-ended --occurred-at 2026-07-25T16:30:00-05:00 --subject person-departing-worker --json
 ```
 
-Run `npx filegrc obligations` first to preview every task, owner, deadline, and requested proof for each available Policy Event. The trigger command creates one `obligation-event` and adds its full set of Action Items to the Work Queue in a single validated write. Its success output names the event, task count, task IDs, and deadlines. Hour-based deadlines require an RFC 3339 event timestamp so an immediate or 24-hour cutoff is exact. Day-based deadlines use the event’s calendar date. Link the requested completion resources and evidence to each action item, then mark the actions done and the event complete. Every generated action has a cutoff. FileGRC applies a 30-day deadline when a custom event obligation omits one.
+Run `npx filegrc obligations` first to preview every task, owner, deadline, and requested proof for each available Policy Event. The trigger command creates one `obligation-event` and adds its full set of Action Items to the Work Queue in a single validated write. Its success output names the event, task count, task IDs, and deadlines. Hour-based deadlines require an RFC 3339 event timestamp so an immediate or 24-hour cutoff is exact. Day-based deadlines use the event’s calendar date. Link the requested completion resources and evidence to each action item, then mark the actions done and the event complete. Every generated action has a cutoff. filegrc applies a 30-day deadline when a custom event obligation omits one.
 
 Complete an event action and link its new proof in one validated write:
 
@@ -150,7 +136,7 @@ npx filegrc complete-action action-item-id completion-record.json --completed-on
 npx filegrc complete-event obligation-event-id --completed-on 2026-07-25
 ```
 
-FileGRC rejects a completion resource whose type does not match the obligation. It will close the event only after every action has its requested proof.
+filegrc rejects a completion resource whose type does not match the obligation. It will close the event only after every action has its requested proof.
 
 ## Headless Markdown
 
@@ -161,7 +147,7 @@ npx filegrc content risk-assessment risk-assessment-2026 --json
 npx filegrc content risk-assessment risk-assessment-2026 --write updated-assessment.md
 ```
 
-Run `filegrc guide <type>` to get slot names. Policies use `content`, meetings use `agenda` and `minutes`, and implicit long-form work uses `record`. FileGRC derives the path and rejects content that does not belong to the record.
+Run `filegrc guide <type>` to get slot names. Policies use `content`, meetings use `agenda` and `minutes`, and implicit long-form work uses `record`. filegrc derives the path and rejects content that does not belong to the record.
 
 ## Program readiness and the candidate period
 
@@ -169,7 +155,7 @@ Prepare the management program before creating an audit engagement:
 
 ```sh
 npx filegrc program-readiness
-npx filegrc program-readiness --require-ready --json
+npx filegrc program-readiness --require-ready --summary --json
 ```
 
 The Evidence Ready gate requires:
@@ -178,15 +164,15 @@ The Evidence Ready gate requires:
 2. Active policies with completed text, separate management approval, real approval and effective dates, and linked controls.
 3. Implemented controls with an owner, actual procedure, scope, cadence, evidence source, mappings, implementation date, and every eligible linked Work Queue schedule running.
 4. Active authoritative systems with evidence source roles, access owners, and repeatable extraction instructions in Record Markdown.
-5. A verified `test-export` or `test-capture` evidence record for each selected control family that relies on evidence from outside FileGRC.
+5. A verified `test-export` or `test-capture` evidence record for each selected control family that relies on evidence from outside filegrc.
 
-Completing onboarding creates draft External Evidence records only for evidence that must come from other systems and does not already have a dedicated Step 5 record. FileGRC-managed records, such as risk assessments, meetings, vendor reviews, attestations, vulnerability scans, penetration tests, backup tests, exercises, exceptions, and findings, do not need a separate collection test. Put any fixed external artifact in an External Evidence record and link it from the operating record. For each generated draft, choose its authoritative source System, attach or reference the real result, record its collector and classification, then have another person verify it. Run `npx filegrc evidence-test-drafts` to create any drafts needed after the control set changes.
+Onboarding does not create External Evidence records. After confirming the applicable controls and authoritative source Systems, run `npx filegrc evidence-test-drafts --preview --json` and review the proposed collection tests. Then run `npx filegrc evidence-test-drafts` to create the missing drafts. filegrc-managed records, such as risk assessments, meetings, vendor reviews, attestations, vulnerability scans, penetration tests, backup tests, exercises, exceptions, and findings, do not need a separate collection test. Put any fixed external artifact in an External Evidence record and link it from the operating record. For each created draft, choose its authoritative source System, attach or reference the real result, record its collector and classification, then have another person verify it.
 
 When the gate passes, set `workspace.candidatePeriodStart` to the date reliable evidence collection begins. Do not backdate it. `candidatePeriodStart` and `candidatePeriodEnd` express management’s target. They do not establish the final report period.
 
 Maintain risk assessments and the risk register while the program operates. Complete assessments on schedule and after material changes, and add or update controls when the conclusions require a different response. Audit preparation still checks for a current, independently reviewed assessment.
 
-Record complementary customer or subservice controls after the internal control set is defined. `complementary-control.relatedControlIds` is the source of truth for those links. FileGRC derives the reverse connections for Control pages and evidence packets.
+Record complementary customer or subservice controls after the internal control set is defined. `complementary-control.relatedControlIds` is the source of truth for those links. filegrc derives the reverse connections for Control pages and evidence packets.
 
 ## Audit preparation and evidence packets
 
@@ -200,20 +186,20 @@ npx filegrc audit-readiness audit-2026-type-2 --require-ready --json
 
 The audit record’s `typeOneAsOf`, `periodStart`, and `periodEnd` are the dates agreed with the CPA firm. Keep the workspace candidate dates even when the formal period differs.
 
-Preparation creates a separate system description, management assertion, and management representation document for the engagement from the local starter templates. Type 2 preparation also creates a period completeness statement and one `audit-population` record for each standard population. It is safe to run again and does not approve documents, mark controls implemented, or create evidence. Do not reuse one completed management document across engagements.
+{{audit_preparation_guidance}}
 
 Review both evidence paths against the exact firm-agreed date or period:
 
-1. FileGRC Evidence consists of dated Step 5 operating records. Complete each applicable record, link it to the Controls it supports, record the result in structured fields or Markdown, and link any external artifact needed to support that result.
+1. filegrc Evidence consists of dated Step 5 operating records. Complete each applicable record, link it to the Controls it supports, record the result in structured fields or Markdown, and link any external artifact needed to support that result.
 2. External Evidence consists of verified `evidence` records from authoritative Systems. Confirm the source System, audit date or period, Control links, collector, verifier, and fixed attachment or approved external reference.
 
-Audit Readiness reports coverage for both paths. The packet includes the matching FileGRC records and Markdown with Git history, plus External Evidence records, retained attachments, delivery indexes, and checksums.
+Audit Readiness reports coverage for both paths. The packet includes the matching filegrc records and Markdown with Git history, plus External Evidence records, retained attachments, delivery indexes, and checksums.
 
 Near the end of fieldwork, link a verified fixed-format copy of the signed management representation letter to its engagement-specific document. Date it on or after the Type 1 date or Type 2 period end. A representation that is still marked for later blocks packet delivery.
 
 Catalog each authoritative source under Systems and assign its `evidenceSourceKinds`. A third-party application is still a System because it operates controls or produces evidence. Create a separate Vendor for its provider and connect the System through `vendorId`; keep contracts, due diligence, and supplier risk on the Vendor. Name the people who can access system reports and keep extraction instructions in the System's Record Markdown. For each Type 2 population, select one source system and export the exact audit period. Split a population when different systems or queries produce its items. Link a verified `population-export` evidence record that names the same source system and stores the query or report parameters, generation time, timezone, count, completeness check, and accuracy check. A zero count still requires the source export and query. A population linked to an in-scope control cannot be marked not applicable.
 
-Every evidence record names its collector. Verified evidence also names its verifier and verification date. Use `sourceSystemId` for system exports, `sourceResourceIds` for FileGRC records, and `sourceCommit` to bind the evidence to repository state.
+Every evidence record names its collector. Verified evidence also names its verifier and verification date. Use `sourceSystemId` for system exports, `sourceResourceIds` for filegrc records, and `sourceCommit` to bind the evidence to repository state.
 
 Preview coverage before writing output:
 
@@ -223,15 +209,15 @@ npx filegrc evidence-packet --audit audit-2026-type-2
 npx filegrc evidence-packet --audit audit-2026-type-2 --preview --require-ready
 ```
 
-The packet includes records explicitly related to the selected engagement, its systems, controls, criteria, policies, evidence, and dependencies. It does not include unrelated dated records from the workspace. A Type 2 packet adds FileGRC Evidence, recurring obligation occurrences, event workflows, and management population reconciliations. Output includes a control matrix with separate FileGRC Evidence and External Evidence columns, source-system index, external-evidence delivery index, population index, evidence index, committed historical source versions, and SHA-256 checksums. Output under `.filegrc/evidence-packets/` is derived and must not be hand-edited or committed.
+The packet includes records explicitly related to the selected engagement, its systems, controls, criteria, policies, evidence, and dependencies. It does not include unrelated dated records from the workspace. A Type 2 packet adds filegrc Evidence, recurring obligation occurrences, event workflows, and management population reconciliations. Output includes a control matrix with separate filegrc Evidence and External Evidence columns, source-system index, external-evidence delivery index, population index, evidence index, committed historical source versions, and SHA-256 checksums. Output under `.filegrc/evidence-packets/` is derived and must not be hand-edited or committed.
 
-Treat a packet as ready for management delivery only when its status is `delivery-ready`, its review list is clear, and its manifest names a clean Git revision. This means FileGRC's management checks passed. It does not mean the engagement team found the evidence sufficient or appropriate. The generator copies raw records, Markdown, and local fixed attachments. It never fetches external references. Reconcile `external-evidence-index.csv` to the auditor portal or other approved delivery system before telling the engagement team that submission is complete.
+Treat a packet as ready for management delivery only when its status is `delivery-ready`, its review list is clear, and its manifest names a clean Git revision. This means filegrc's management checks passed. It does not mean the engagement team found the evidence sufficient or appropriate. The generator copies raw records, Markdown, and local fixed attachments. It never fetches external references. Reconcile `external-evidence-index.csv` to the auditor portal or other approved delivery system before telling the engagement team that submission is complete.
 
-Link a control test to its `audit-population` record when sampling applies. Link item-level sample evidence separately. Management owns population completeness and accuracy. The auditor owns sample selection, independent testing, exception evaluation, and the report opinion. The auditor or publisher also supplies the authoritative criteria and examination guidance. FileGRC stores references and orientation text, not licensed criteria.
+Link a control test to its `audit-population` record when sampling applies. Link item-level sample evidence separately. Management owns population completeness and accuracy. The auditor owns sample selection, independent testing, exception evaluation, and the report opinion. The auditor or publisher also supplies the authoritative criteria and examination guidance. filegrc stores references and orientation text, not licensed criteria.
 
 ## Content and approvals
 
-The seed policy owner is {{policy_owner_name}} and the reporting address is {{security_contact_email}}. Replace ownership or contacts when responsibilities change.
+The seed policy owner is {{policy_owner_name}} at {{policy_owner_email}}, and the security reporting address is {{security_contact_email}}. Replace ownership or contacts when responsibilities change.
 
 Appoint an independent management reviewer during policy review, not as a condition of defining the service boundary. The reviewer must be separate from the policy owner and able to challenge the owner’s decisions. Most organizations assign another internal leader or manager. An external reviewer is also allowed, and a one-person company needs one because no second internal person is available. The reviewer chairs Security and Risk Oversight and approves policies and governed documents.