create-filegrc 0.3.0 → 0.3.2

package/README.md

@@ -11,10 +11,37 @@ npm run serve
 
 Setup asks for the legal organization name, the initial policy owner and their email, a security reporting address, and the program timezone. The generated private project includes a starter Security program, Program Readiness, a policy-driven Work Queue, Policy Events that add linked tasks, later audit preparation, evidence packets, and one dependency: `filegrc`.
 
+Creation has two layers. The five-record foundation contains workspace settings, the initial owner, the oversight team, renderer settings, and the filegrc system of record. The default `security` starter adds the framework references, proposed policies, controls, obligations, documents, and training records. Pass `--starter foundation` when you want to stop before selecting a framework.
+
+For one noninteractive run, pass company and service fields together or use `--config setup.json`. The optional `setup` object defines the service boundary and management goal after installation. Use `--filegrc-package <directory>` to exercise unpublished local engine changes instead of installing the registry release. This writes a machine-local `file:` dependency, so replace it with a released version before sharing the generated workspace.
+
+```json
+{
+  "companyName": "Example Company",
+  "policyOwnerName": "Security Owner",
+  "policyOwnerEmail": "owner@example.com",
+  "securityContactEmail": "security@example.com",
+  "timezone": "America/Chicago",
+  "starter": "security",
+  "setup": {
+    "serviceName": "Example Service",
+    "boundary": "The production service and supporting infrastructure.",
+    "criticality": "high",
+    "dataClassification": "Confidential",
+    "internetExposed": true,
+    "programGoal": "type-2"
+  }
+}
+```
+
+```sh
+npx create-filegrc@latest company-grc --config setup.json
+```
+
 Generated workspaces also include layered `AGENTS.md` instructions and model-driven headless commands. `filegrc program-path` gives agents the same six steps, exact page guidance, current status, and next actions shown in the renderer. Agents can define program scope, approve policies, implement controls, test External Evidence, complete policy work, trigger event tasks, and prepare later audit packets through the same domain functions used by the renderer.
 
 Git is initialized when needed. The browser can create local commits before a remote is configured.
 
 Creation output reports the resolved filegrc version, program timezone, starter record counts, whether installation ran, and whether the target joined an existing Git worktree or received a new repository.
 
-Use `npx create-filegrc@latest --help` for non-interactive options.
+Use `npx create-filegrc@latest --help` for noninteractive options.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-filegrc",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Create a filegrc workspace for a SOC 2 program",
   "license": "MIT",
   "repository": {

package/src/cli.js

@@ -1,17 +1,45 @@
 import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
 import { createFilegrc } from "./index.js";
 
 export async function runCli(argv = process.argv.slice(2)) {
-  const { target, options } = parseArgs(argv);
+  const parsed = parseArgs(argv);
+  const config = parsed.options.config ? await readConfig(parsed.options.config) : {};
+  const organization = config.organization && typeof config.organization === "object"
+    ? config.organization
+    : {};
+  const options = {
+    ...organization,
+    ...config,
+    ...parsed.options,
+    setup: {
+      ...(config.setup || {}),
+      ...parsed.setup
+    }
+  };
+  delete options.organization;
+  delete options.config;
+  delete options.target;
+  if (!Object.keys(options.setup).length) delete options.setup;
+  const target = parsed.target ?? config.target ?? "filegrc-program";
   if (options.help) return printHelp();
   if (options.version) return printVersion();
   const result = await createFilegrc({ target, ...options });
   console.log(`Created ${result.target}`);
-  console.log(`filegrc ${result.engineVersion}: ${result.install === "installed" ? "installed" : "installation skipped"}`);
+  console.log(
+    `filegrc ${result.engineVersion}${result.enginePackage ? ` from ${result.enginePackage}` : ""}: ` +
+    `${result.install === "installed" ? "installed" : "installation skipped"}`
+  );
   console.log(`Git: ${result.gitMode === "existing-worktree" ? "joined existing worktree" : "initialized new repository"}`);
+  if (result.gitDetached) {
+    console.log("Warning: detached HEAD detected. Check out a branch before using browser commit, pull, or push.");
+  }
   console.log(`Timezone: ${result.values.timezone}`);
+  for (const stage of result.stages) {
+    console.log(`Stage ${stage.id}: ${stage.status}${stage.status === "created" ? ` (${stage.records} records)` : ""}`);
+  }
   console.log(
-    `Program baseline: ${result.resourceCounts.total} records, including ` +
+    `${result.setup ? "Workspace after setup" : "Program baseline"}: ${result.resourceCounts.total} records, including ` +
     `${result.resourceCounts.byType.requirement || 0} requirements, ` +
     `${result.resourceCounts.byType.control || 0} controls, and ` +
     `${result.resourceCounts.byType.obligation || 0} obligations.`
@@ -19,20 +47,40 @@ export async function runCli(argv = process.argv.slice(2)) {
   console.log("");
   console.log(`  cd ${shellQuote(result.target)}`);
   if (options.install === false) console.log("  npm install");
-  console.log("  npx filegrc setup");
+  if (!result.setup) console.log("  npx filegrc setup");
+  if (result.setup) console.log("  npx filegrc program-path --next --json");
   console.log("  npm run validate");
   console.log("  npm run serve");
   console.log("");
-  console.log("Review the starter drafts, then commit the approved baseline.");
+  if (result.setup) {
+    console.log(`Service setup: ${result.setup.system.id} (${result.setup.system.status}), target ${result.setup.target.assuranceGoal}.`);
+    if (result.setup.draft) {
+      console.log("Planned and in scope means selected for scope review, not approved or active.");
+    }
+  }
+  console.log("Immediate human decisions:");
+  console.log(result.setup?.target.assuranceGoal && result.setup.target.assuranceGoal !== "none"
+    ? `  1. Confirm the selected assurance goal with management: ${assuranceGoalLabel(result.setup.target.assuranceGoal)}.`
+    : "  1. Select and confirm the assurance goal.");
+  console.log("  2. Appoint an independent reviewer who is separate from the policy owner.");
+  console.log("Review the generated records, then commit the approved baseline.");
 }
 
 function shellQuote(value) {
   return `'${String(value).replaceAll("'", "'\\''")}'`;
 }
 
+function assuranceGoalLabel(value) {
+  if (value === "soc-2-type-1") return "SOC 2 Type 1";
+  if (value === "soc-2-type-2") return "SOC 2 Type 2";
+  if (value === "readiness") return "Program Readiness";
+  return "No assurance goal selected";
+}
+
 function parseArgs(argv) {
   let target;
   const options = {};
+  const setup = {};
   for (let index = 0; index < argv.length; index += 1) {
     const value = argv[index];
     if (!value.startsWith("-") && !target) {
@@ -46,15 +94,26 @@ function parseArgs(argv) {
     else if (name === "yes" || name === "y") options.yes = true;
     else if (name === "force") options.force = true;
     else if (name === "no-install") options.install = false;
+    else if (name === "config") options.config = next();
     else if (name === "company-name") options.companyName = next();
     else if (name === "policy-owner-name") options.policyOwnerName = next();
     else if (name === "policy-owner-email") options.policyOwnerEmail = next();
     else if (name === "security-contact-email") options.securityContactEmail = next();
     else if (name === "timezone") options.timezone = next();
+    else if (name === "starter") options.starter = next();
     else if (name === "filegrc-version") options.filegrcVersion = next();
+    else if (name === "filegrc-package") options.filegrcPackage = next();
+    else if (name === "service-name") setup.serviceName = next();
+    else if (name === "boundary") setup.boundary = next();
+    else if (name === "service-owner") setup.ownerId = next();
+    else if (name === "criticality") setup.criticality = next();
+    else if (name === "classification") setup.dataClassification = next();
+    else if (name === "internet-exposed") setup.internetExposed = booleanOption(next(), "internet-exposed");
+    else if (name === "program-goal") setup.programGoal = next();
+    else if (name === "setup-draft") setup.draft = true;
     else throw new Error(`Unknown option "${value}".`);
   }
-  return { target: target ?? "filegrc-program", options };
+  return { target, options, setup };
 }
 
 function printHelp() {
@@ -63,12 +122,23 @@ function printHelp() {
 Create a filegrc workspace for a SOC 2 program.
 
 Options:
+  --config <json-file|->            Read creation and optional setup values
   --company-name <legal-name>       Legal organization name
   --policy-owner-name <name>        Initial policy owner
   --policy-owner-email <email>      Policy owner's email address
   --security-contact-email <email>  Security reporting address
   --timezone <iana-timezone>        Program timezone, such as America/Chicago
+  --starter <profile>               security (default) or foundation
   --filegrc-version <version>       Override resolved engine version
+  --filegrc-package <directory>     Install an unpublished local filegrc package
+  --service-name <name>             Complete service setup after creation
+  --boundary <description>          Initial service boundary
+  --service-owner <person-id>       Defaults to person-policy-owner
+  --criticality <level>             low, medium, high, or critical
+  --classification <name>           Initial data classification
+  --internet-exposed <bool>         true or false
+  --program-goal <goal>             none, readiness, type-1, or type-2
+  --setup-draft                     Save combined service setup as a draft
   --no-install                      Write files and a preliminary lockfile only
   --force                           Allow a non-empty target without overwriting files
   --yes                             Use generic prompt defaults
@@ -80,3 +150,26 @@ async function printVersion() {
   const packageJson = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
   console.log(packageJson.version);
 }
+
+async function readConfig(path) {
+  const source = path === "-"
+    ? await readStdin()
+    : await readFile(resolve(String(path)), "utf8");
+  const parsed = JSON.parse(source);
+  if (!parsed || Array.isArray(parsed) || typeof parsed !== "object") {
+    throw new Error("Creation config must be a JSON object.");
+  }
+  return parsed;
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+function booleanOption(value, name) {
+  if (value === "true") return true;
+  if (value === "false") return false;
+  throw new Error(`--${name} must be true or false.`);
+}

package/src/defaults.js

@@ -884,11 +884,11 @@ const obligations = [
   }
 ];
 
-export function baselineRecordPaths() {
-  return baselineRecordFiles("2000-01-01").map(({ path }) => path);
+export function baselineRecordPaths(starter = "security") {
+  return baselineRecordFiles("2000-01-01", starter).map(({ path }) => path);
 }
 
-export function baselineRecordFiles(effectiveDate) {
+export function baselineRecordFiles(effectiveDate, starter = "security") {
   const framework = {
     schemaVersion: 1,
     id: FRAMEWORK_ID,
@@ -1006,20 +1006,25 @@ export function baselineRecordFiles(effectiveDate) {
     policyIds: obligation.policyIds
   }));
 
+  const foundation = [
+    recordFile("systems", programRepository),
+    recordFile("teams", team)
+  ];
+  if (starter === "foundation") return foundation;
+  if (starter !== "security") throw new Error(`Unknown starter profile "${starter}".`);
   return [
     recordFile("frameworks", framework),
     recordFile("frameworks", descriptionFramework),
     ...commonRequirements.map((record) => recordFile("requirements", record)),
     ...descriptionRequirements.map((record) => recordFile("requirements", record)),
     ...controlRecords.map((record) => recordFile("controls", record)),
-    recordFile("systems", programRepository),
-    recordFile("teams", team),
+    ...foundation,
     ...obligationRecords.map((record) => recordFile("obligations", record))
   ];
 }
 
-export async function writeBaselineRecords(target, effectiveDate) {
-  for (const { path: relativePath, record } of baselineRecordFiles(effectiveDate)) {
+export async function writeBaselineRecords(target, effectiveDate, starter = "security") {
+  for (const { path: relativePath, record } of baselineRecordFiles(effectiveDate, starter)) {
     const path = join(target, relativePath);
     await mkdir(dirname(path), { recursive: true });
     await writeFile(path, `${JSON.stringify(record, null, 2)}\n`, { encoding: "utf8", flag: "wx" });

package/src/index.js

@@ -4,33 +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 = {}) {
   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);
-  const resourceCounts = await summarizeResources(target);
+  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) {
@@ -40,16 +50,36 @@ export async function createFilegrc(options = {}) {
   }
   const joinedExistingWorktree = await isInsideGitWorktree(target);
   if (!joinedExistingWorktree) await run("git", ["init"], target);
+  const gitHead = await inspectGitHead(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"
+    gitMode: joinedExistingWorktree ? "existing-worktree" : "initialized",
+    gitBranch: gitHead.branch,
+    gitDetached: gitHead.detached
   };
 }
 
+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 {
@@ -65,6 +95,28 @@ 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,
@@ -161,9 +213,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));
@@ -192,20 +244,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}`);
@@ -213,20 +267,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"
@@ -242,6 +298,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 })) {
@@ -265,16 +328,137 @@ async function summarizeResources(target) {
   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.3.0",
+    version: "0.3.2",
     lockfileVersion: 3,
     requires: true,
     packages: {
       "": {
         name,
-        version: "0.3.0",
+        version: "0.3.2",
         dependencies: { filegrc: versionRange }
       }
     }
@@ -291,6 +475,20 @@ async function isInsideGitWorktree(target) {
   }
 }
 
+async function inspectGitHead(target) {
+  try {
+    const { stdout } = await execute("git", ["symbolic-ref", "--quiet", "--short", "HEAD"], { cwd: target });
+    return { branch: stdout.trim() || null, detached: false };
+  } catch {
+    try {
+      await execute("git", ["rev-parse", "--verify", "HEAD"], { cwd: target });
+      return { branch: null, detached: true };
+    } catch {
+      return { branch: null, detached: false };
+    }
+  }
+}
+
 async function run(command, args, cwd) {
   try {
     return await execute(command, args, { cwd, maxBuffer: 10_000_000 });

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.
 
@@ -12,13 +12,13 @@ Do not guess a resource type, field name, enum value, relationship, or file path
 
 ```sh
 npx filegrc guide --json
-npx filegrc program-path --json
+npx filegrc program-path --next --json
 npx filegrc guide risk-assessment --json
 npx filegrc list person --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.
+`program-path --next --json` gives agents the current step and first action. Use `--summary` for all six step statuses or `--current` for the current step’s full renderer Instructions, Use, Policy Basis, commands, and next actions. 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.
 
 For a new record, generate a mutation envelope:
 
@@ -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 add the real reviewers and operators, finish the oversight team, and confirm the 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
 
@@ -180,7 +166,7 @@ The Evidence Ready gate requires:
 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.
 
-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.
 
@@ -200,7 +186,7 @@ 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:
 

package/template/README.md

@@ -4,28 +4,9 @@
 
 Run a SOC 2 program as files in Git.
 
-filegrc gives a founder-led engineering team one place to adopt policies, implement controls, test External Evidence collection, run recurring compliance work, and prepare an audit. JSON holds structured records, Markdown holds long-form work, and Git supplies the change history.
+filegrc gives founder-led engineering teams one place to adopt policies, implement controls, run recurring work, collect evidence, and prepare an audit.
 
-There is no separate application database. The repository is the program, so engineers and agents can use the same data through the web app, a text editor, or the CLI.
-
-## Why it exists
-
-SOC 2 work tends to scatter across documents, calendars, tickets, screenshots, and the auditor’s request list. That makes it hard to answer basic questions: What is due? Which policy requires it? What changed during the audit period? Is the evidence complete?
-
-filegrc keeps that work connected:
-
-- A starter Security program links criteria references, policies, planned controls, owners, and schedules.
-- Work Queue turns policy timing into upcoming, due, and overdue work.
-- Policy Events add the required hiring, departure, vendor, incident, and change tasks to the Work Queue.
-- Program Readiness says whether management can begin a candidate Type 2 evidence period without an audit record.
-- Audit Readiness starts later with the CPA engagement, formal period, fieldwork documents, populations, and evidence delivery.
-- The packet builder produces a scoped, indexed delivery with source files, attachments, history, and checksums.
-
-The starter content is a proposal, not a claim of compliance. Review every policy and planned control against how your company actually operates before approving it.
-
-## Start a workspace
-
-You need Node.js 20 or newer and Git.
+It is open source, MIT licensed, and runs locally.
 
 ```sh
 npx create-filegrc@latest company-grc
@@ -34,94 +15,64 @@ npm run validate
 npm run serve
 ```
 
-Setup asks for the legal organization name, the initial policy owner and their email, a security reporting address, and the program timezone. It initializes Git when needed. The first local run then defines the initial service boundary and an optional program goal. A Type 2 choice records management intent, not an audit engagement. Completing onboarding opens Step 1 so you can add the real reviewers and operators, finish the oversight team, and confirm the criteria, commitments, vendors, and systems before moving on.
-
-Open the printed local URL. You can commit locally from Repository without configuring a remote. Add a remote when the team is ready to share the workspace, then the browser can pull with rebase and push reviewed commits.
-
-The creation summary reports the resolved engine version, program timezone, starter record counts, install result, and whether the target joined an existing Git worktree. Generated workspaces receive an organization-specific README with their engine version, validation commands, and remaining setup work.
+Requires Node.js 20 or newer and Git.
 
 ## How it works
 
-1. Confirm the program’s people and oversight team, applicable criteria, commitments, material vendors, and in-scope systems.
-2. Review and activate the policies with a separate management reviewer, who is usually internal and may be external.
-3. Tailor the starter controls, add each owner, actual procedure, scope, cadence, evidence source, 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. Open each generated External Evidence draft, choose its authoritative source System, collect the named artifact, and have another person verify it.
-5. Start the management candidate period, maintain risk assessments and risks, update controls when needed, work the filegrc queue, and preserve dated evidence.
-6. Engage a CPA firm, record the separate firm-agreed period, review filegrc Evidence and External Evidence, prepare fieldwork, and generate the evidence packet.
-
-Long-form policies, procedures, plans, minutes, training, assertions, and audit responses are Markdown companions beside their JSON records. Screenshots, signed acknowledgements, reports, and fixed exports are attachments linked through evidence records.
+The repository is the program. There is no separate application database.
 
-Third-party software is usually both a System and a Vendor. The application is the System because it operates controls and produces evidence. The provider is the Vendor because contracts, due diligence, and supplier risk belong to that relationship. Link the System to the Vendor with `vendorId`, and link exported evidence to the System.
+- **JSON** holds records that filegrc validates, filters, and connects.
+- **Markdown** holds policies, procedures, plans, minutes, and narratives.
+- **Git** supplies authors, timestamps, revisions, diffs, and commit messages.
 
-## Run the program
+Use the same source through the local web app, a text editor, the CLI, or CI. Browser and CLI actions call the same rules, so engineers and agents see the same validation and readiness results.
 
-Use Overview to follow one six-step path: define scope, approve policies, implement controls, test External Evidence, operate the program, then complete the audit. Steps 1 through 4 and Step 6 open an overview with instructions, record links, progress, and completion status. Step 5 opens Policy Events and the Work Queue because operation is ongoing rather than a one-time checklist. The progress tracker opens the first incomplete step.
+## One path from setup to audit
 
 ![filegrc SOC 2 program overview](docs/filegrc-home.png)
 
-Use Work Queue for recurring work, Policy Event tasks, and other assigned follow-up. Trigger a Policy Event when the underlying change occurs, and filegrc adds its required actions to the queue with their owners and deadlines. Create a separate Action Item only when follow-up needs its own assignee, deadline, and completion proof. Each queue item shows its due window or deadline. Link dated proof to close the work.
+1. **Define scope.** Confirm owners, criteria, commitments, vendors, and in-scope systems.
+2. **Approve policies.** Tailor the proposals and record separate owners and reviewers.
+3. **Implement controls.** Add the real procedure, scope, cadence, and evidence source.
+4. **Test evidence collection.** Collect and verify evidence from each authoritative system.
+5. **Operate the program.** Work the queue, trigger Policy Events, maintain risks, and preserve dated evidence.
+6. **Audit.** Record the CPA engagement and agreed period, support fieldwork, and build the packet.
 
-Use the resource pages to maintain systems, people, vendors, risks, controls, tests, incidents, training, meetings, and External Evidence. The question-mark guide on each list explains what the record type is for, which policies call for it, and when to update it.
+The Program Overview shows what is done, what is blocked, and what to do next.
 
-Agents use the same logic headlessly:
-
-```sh
-npx filegrc guide risk-assessment --json
-npx filegrc program-path --json
-npx filegrc scaffold risk-assessment --title "2026 Annual Risk Assessment"
-npx filegrc list risk --json
-npx filegrc obligations --json
-npx filegrc program-readiness --summary --json
-npx filegrc complete obligation-id completion-record.json
-npx filegrc trigger person-started --occurred-on 2026-07-25 --subject person-id
-npx filegrc complete-action action-item-id completion-record.json --completed-on 2026-07-25
-npx filegrc complete-event obligation-event-id --completed-on 2026-07-25
-npx filegrc search "access review"
-```
+## The routine work stays connected
 
-`program-path` reports the same six steps, current status, page order, exact Instructions, Use, Policy Basis, and next actions shown in the renderer. `program-readiness --summary --json` reports compact stage counts and next actions; omit `--summary` when you need every readiness item. `guide` reports that same page guidance for one resource, plus timing, required fields, valid values, relationship candidates, and Markdown locations. `scaffold` produces the same JSON and Markdown mutation shape used by the browser. Read `AGENTS.md` and `data/AGENTS.md` for the full headless workflow.
+- **Work Queue** turns policy schedules and follow-up into upcoming, due, and overdue work.
+- **Policy Events** create the right tasks for hiring, departures, incidents, vendor changes, and other events.
+- **Program Readiness** checks whether management can begin a reliable evidence period.
+- **Audit Readiness** checks the engagement, period, documents, evidence, and Type 2 populations.
+- **Evidence packets** collect the scoped records, attachments, history, indexes, and checksums for delivery.
 
-## Start the evidence period
-
-Program Readiness works without an audit ID or CPA firm:
-
-```sh
-npx filegrc program-readiness --json
-npx filegrc program-readiness --require-ready
-```
-
-The Evidence Ready gate requires defined scope, effective policies, implemented controls, configured authoritative systems, and verified collection for external evidence that does not already have a dedicated Step 5 record. Put scan reports, backup output, and other fixed artifacts in External Evidence records, then link them from the applicable Step 5 operating records. Starter obligations remain enabled proposals until their governing policies are effective and at least one linked control is implemented. A filegrc-managed control cannot be implemented while one of its linked Work Queue schedules is paused or waiting for policy approval.
-
-When the gate passes, record `candidatePeriodStart` on the workspace on the date reliable collection begins. This is management’s candidate Type 2 period. Do not backdate it. The later audit record keeps the separate period agreed with the CPA firm.
+![filegrc audit readiness](docs/filegrc-audit.png)
 
-## Prepare the audit
+Starter records connect policies, controls, owners, systems, evidence, and schedules. They are proposals, so review them against how your company actually works before approval.
 
-After engaging a CPA firm, create the audit record with the firm, scope, and exact agreed date or period. Audit Readiness checks the program foundation, engagement, formal scope and dates, management documents, filegrc Evidence, External Evidence, and Type 2 populations.
+## Built for engineers and agents
 
-![filegrc audit readiness](docs/filegrc-audit.png)
-
-For a Type 2 audit, reconcile each complete period population to its authoritative system after the period closes. A zero-item population still needs its source export and query. filegrc Evidence consists of dated operating records and their Markdown and Git history. External Evidence consists of verified exports, reports, screenshots, signed files, and approved external references. The packet compiles both paths with the selected records, attachments, indexes, historical versions, and SHA-256 checksums.
+The browser is helpful, but it is not required. An agent can discover the model, inspect valid relationships, create records, complete scheduled work, trigger events, and check the result from the CLI.
 
 ```sh
-npx filegrc prepare-audit audit-id
+npx filegrc program-path --next --json
+npx filegrc guide risk-assessment --json
+npx filegrc obligations --json
+npx filegrc program-readiness --summary --json
 npx filegrc audit-readiness audit-id --json
 npx filegrc evidence-packet --audit audit-id
 ```
 
-filegrc checks management preparation and packet integrity. The independent CPA firm still selects samples, tests controls, evaluates exceptions, decides whether evidence is sufficient, and issues the SOC 2 report.
-
-Early CPA engagement remains available when a customer deadline, unusual scope, or other timing risk needs input before the program reaches Evidence Ready. It is optional, not the default first action.
-
-## What belongs elsewhere
-
-filegrc does not replace workforce, identity, source-control, deployment, infrastructure, monitoring, endpoint, backup, vulnerability, training, signature, procurement, contract, or vendor-risk systems.
+Read `AGENTS.md` and `data/AGENTS.md` inside a generated workspace for the full headless workflow.
 
-Catalog each authoritative system in filegrc, record how to export from it, and attach or reference the fixed evidence when Audit Readiness asks for it. The generated external-delivery index identifies files that still need to be supplied through an auditor portal or another approved channel.
+## Clear boundaries
 
-The starter uses the SOC 2 Security category and does not include licensed criteria text. Add Availability, Processing Integrity, Confidentiality, or Privacy only when they are in scope.
+filegrc manages GRC records and audit evidence. Your workforce, identity, source control, infrastructure, monitoring, endpoint, backup, training, signature, procurement, and vendor systems still operate the controls and produce source evidence.
 
-## Repository safety
+The independent CPA firm still selects samples, tests controls, evaluates exceptions, decides whether evidence is sufficient, and issues the SOC 2 report.
 
-The editable server has no authentication and binds to loopback by default. Do not expose it to an untrusted network. Use `npm run build` for a read-only site.
+Do not put secrets or personal data that may need erasure into Git. The editable local server has no authentication and binds to loopback by default.
 
-Do not put secrets or personal data that may need erasure into Git. Read `AGENTS.md` before broad record changes or automation work.
+Learn more at [filegrc.com](https://filegrc.com) or [view the source on GitHub](https://github.com/Sunpeak-AI/filegrc).

package/template/WORKSPACE.md

@@ -1,8 +1,8 @@
-# {{company_name}} SOC 2 Program
+# {{program_title}}
 
-This private workspace holds {{company_name}}'s SOC 2 program records and audit evidence. JSON under `data/` stores structured records, Markdown stores long-form work, and Git records reviewed changes.
+{{program_summary}}
 
-The workspace uses filegrc {{filegrc_version}} through the dependency range `{{filegrc_version_range}}`.
+The workspace uses filegrc {{filegrc_version}} through the dependency spec `{{filegrc_version_range}}`.
 
 ## Work locally
 
@@ -20,22 +20,13 @@ Agents and terminal users can inspect the workspace without the browser:
 
 ```sh
 npx filegrc guide --json
-npx filegrc program-path --json
+npx filegrc program-path --next --json
 npx filegrc obligations --json
 npx filegrc validate --json
 ```
 
 Read `AGENTS.md` and `data/AGENTS.md` before broad changes.
 
-## Finish initial setup
-
-The starter policies, controls, and obligations are proposals. They do not state that {{company_name}} 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. Open each generated External Evidence draft, choose its authoritative source System, collect the named artifact, and have another person verify it.
-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. `npx filegrc obligations` previews every event task, owner, deadline, and requested proof before the trigger creates anything.
-6. Engage a CPA firm, record the separate firm-agreed period in an audit record, review filegrc Evidence and External Evidence, and prepare fieldwork.
+{{starter_setup}}
 
 filegrc manages GRC records and audit evidence. It does not replace infrastructure logging, monitoring, identity, backup, endpoint, or incident-detection systems.

package/template/data/AGENTS.md

@@ -8,14 +8,14 @@ Treat the installed model as the authority. Do not infer a schema from a nearby
 
 ```sh
 npx filegrc guide --json
-npx filegrc program-path --json
+npx filegrc program-path --next --json
 npx filegrc types --json
 npx filegrc guide RESOURCE_TYPE --json
 npx filegrc list RESOURCE_TYPE --json
 npx filegrc search "TERM" --json
 ```
 
-Use `program-path` to find the current lifecycle step and see the renderer’s exact page Instructions, Use, Policy Basis, commands, and next actions. Use `guide` before any unfamiliar create or status transition. It repeats the page guidance and reports required fields, fields required by a status, enum values, relationship types and candidates, Markdown slots, timing, and exact paths. Use `describe` only when you need the raw model definition.
+Use `program-path --next --json` to find the current lifecycle step and first action. Use `--summary` for all six step statuses or `--current` for the current step’s full renderer Instructions, Use, Policy Basis, commands, and next actions. Use `guide` before any unfamiliar create or status transition. It repeats the page guidance and reports required fields, fields required by a status, enum values, relationship types and candidates, Markdown slots, timing, and exact paths. Use `describe` only when you need the raw model definition.
 
 ## Choose the right record
 

package/template/data/evidence/AGENTS.md

@@ -2,7 +2,7 @@
 
 An evidence record explains what a proof item is, where it came from, what period it supports, who collected it, and which records or controls it supports. The attachment alone is not enough.
 
-Completing onboarding creates draft collection tests only for evidence that must come from systems outside filegrc and does not already have a dedicated Step 5 record. Risk assessments, meetings, vendor reviews, attestations, vulnerability scans, penetration tests, backup tests, exercises, exceptions, and findings do not need a separate test. When one of those operating records needs a fixed external artifact, create or update an External Evidence record for the artifact and link its ID from the operating record. Keep a generated collection test as `draft` until the artifact has actually been captured. Set it to `collected` only after selecting the source System, attaching or referencing the result, and recording the source, date, classification, and collector. Set it to `verified` only after another named person checks it.
+Onboarding does not create collection tests. After confirming applicable controls and authoritative source Systems, preview proposed tests with `npx filegrc evidence-test-drafts --preview --json`, then explicitly create the missing drafts. Risk assessments, meetings, vendor reviews, attestations, vulnerability scans, penetration tests, backup tests, exercises, exceptions, and findings do not need a separate test. When one of those operating records needs a fixed external artifact, create or update an External Evidence record for the artifact and link its ID from the operating record. Keep a created collection test as `draft` until the artifact has actually been captured. Set it to `collected` only after selecting the source System, attaching or referencing the result, and recording the source, date, classification, and collector. Set it to `verified` only after another named person checks it.
 
 ## Create evidence
 

package/template/data/workspace.json

@@ -3,10 +3,10 @@
   "dataModelVersion": "1",
   "id": "workspace",
   "type": "workspace",
-  "title": "{{company_name}} SOC 2 Program",
+  "title": "{{program_title}}",
   "organizationName": "{{company_name}}",
   "timezone": "{{timezone}}",
-  "description": "SOC 2 Security program based on the AICPA Trust Services Criteria.",
+  "description": "{{program_description}}",
   "riskMethodology": {
     "method": "5x5 likelihood and impact",
     "likelihoodScale": ["Rare", "Unlikely", "Possible", "Likely", "Almost certain"],

package/template/package.json

@@ -1,6 +1,6 @@
 {
   "name": "{{project_name}}",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "private": true,
   "description": "filegrc workspace for a SOC 2 program",
   "type": "module",

package/template-parameters.json

@@ -45,6 +45,38 @@
     {
       "key": "filegrc_version_range",
       "source": "resolved-filegrc-version"
+    },
+    {
+      "key": "program_title",
+      "source": "starter-profile"
+    },
+    {
+      "key": "program_description",
+      "source": "starter-profile"
+    },
+    {
+      "key": "program_summary",
+      "source": "starter-profile"
+    },
+    {
+      "key": "starter_setup",
+      "source": "starter-profile"
+    },
+    {
+      "key": "agent_title",
+      "source": "starter-profile"
+    },
+    {
+      "key": "agent_purpose",
+      "source": "starter-profile"
+    },
+    {
+      "key": "starter_baseline",
+      "source": "starter-profile"
+    },
+    {
+      "key": "audit_preparation_guidance",
+      "source": "starter-profile"
     }
   ]
 }