create-filegrc 0.3.0 → 0.3.1

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.1",
   "description": "Create a filegrc workspace for a SOC 2 program",
   "license": "MIT",
   "repository": {

package/src/cli.js

@@ -1,17 +1,42 @@
 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"}`);
   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,11 +44,14 @@ 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");
   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}.`);
+  }
+  console.log("Review the generated records, then commit the approved baseline.");
 }
 
 function shellQuote(value) {
@@ -33,6 +61,7 @@ function shellQuote(value) {
 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 +75,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 +103,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 +131,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,33 @@ 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 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 +92,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 +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));
@@ -192,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}`);
@@ -213,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"
@@ -242,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 })) {
@@ -265,16 +325,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.1",
     lockfileVersion: 3,
     requires: true,
     packages: {
       "": {
         name,
-        version: "0.3.0",
+        version: "0.3.1",
         dependencies: { filegrc: versionRange }
       }
     }

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.
 
@@ -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

@@ -34,6 +34,8 @@ npm run validate
 npm run serve
 ```
 
+The default `security` starter builds the full proposed SOC 2 Security program. Use `--starter foundation` to create only the five structural records when you want to select a framework and program content later. Company and service values can also be supplied together through `create-filegrc --config setup.json`.
+
 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.
@@ -45,7 +47,7 @@ The creation summary reports the resolved engine version, program timezone, star
 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.
+4. After confirming the applicable controls and authoritative source Systems, preview the proposed External Evidence drafts with `npx filegrc evidence-test-drafts --preview --json`. Create only the relevant drafts, collect each 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.
 

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
 
@@ -27,15 +27,6 @@ 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/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.1",
   "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"
     }
   ]
 }