create-filegrc 0.1.0 → 0.3.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 FileGRC contributors
+Copyright (c) 2026 filegrc contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,6 +1,6 @@
 # create-filegrc
 
-Create a Git-native FileGRC workspace for a SOC 2 program:
+Create a Git-native filegrc workspace for a SOC 2 program:
 
 ```sh
 npx create-filegrc@latest company-grc
@@ -9,10 +9,12 @@ npm run validate
 npm run serve
 ```
 
-Setup asks for the company name, the initial policy owner, and a security contact email. The generated private project includes a starter Security program, policy-driven work queue, event checklists, audit preparation, evidence packets, and one dependency: `filegrc`.
+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`.
 
-Generated workspaces also include layered `AGENTS.md` instructions and model-driven headless commands. Agents can discover types, scaffold JSON plus Markdown, inspect relationships, perform CRUD, complete policy work, and prepare audit packets through the same domain functions used by the renderer.
+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.

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "create-filegrc",
-  "version": "0.1.0",
-  "description": "Create a FileGRC workspace for a SOC 2 program",
+  "version": "0.3.0",
+  "description": "Create a filegrc workspace for a SOC 2 program",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Sunpeak-AI/FileGRC.git"
+    "url": "git+https://github.com/Sunpeak-AI/filegrc.git"
   },
   "type": "module",
   "bin": {

package/src/cli.js

@@ -1,21 +1,35 @@
 import { readFile } from "node:fs/promises";
-import { createFileGRC } from "./index.js";
+import { createFilegrc } from "./index.js";
 
 export async function runCli(argv = process.argv.slice(2)) {
   const { target, options } = parseArgs(argv);
   if (options.help) return printHelp();
   if (options.version) return printVersion();
-  const result = await createFileGRC({ target, ...options });
+  const result = await createFilegrc({ target, ...options });
   console.log(`Created ${result.target}`);
+  console.log(`filegrc ${result.engineVersion}: ${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}`);
+  console.log(
+    `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.`
+  );
   console.log("");
-  console.log(`  cd ${result.target}`);
+  console.log(`  cd ${shellQuote(result.target)}`);
   if (options.install === false) console.log("  npm install");
+  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.");
 }
 
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", "'\\''")}'`;
+}
+
 function parseArgs(argv) {
   let target;
   const options = {};
@@ -34,7 +48,9 @@ function parseArgs(argv) {
     else if (name === "no-install") options.install = false;
     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 === "filegrc-version") options.filegrcVersion = next();
     else throw new Error(`Unknown option "${value}".`);
   }
@@ -44,18 +60,20 @@ function parseArgs(argv) {
 function printHelp() {
   console.log(`create-filegrc [directory] [options]
 
-Create a FileGRC workspace for a SOC 2 program.
+Create a filegrc workspace for a SOC 2 program.
 
 Options:
-  --company-name <name>
-  --policy-owner-name <name>
-  --security-contact-email <email>
+  --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
   --filegrc-version <version>       Override resolved engine version
-  --no-install                   Write files and a preliminary lockfile only
-  --force                        Allow a non-empty target without overwriting files
-  --yes                          Use generic prompt defaults
-  --version                      Show the package version
-  --help                         Show this help`);
+  --no-install                      Write files and a preliminary lockfile only
+  --force                           Allow a non-empty target without overwriting files
+  --yes                             Use generic prompt defaults
+  --version                         Show the package version
+  --help                            Show this help`);
 }
 
 async function printVersion() {

package/src/defaults.js

@@ -4,7 +4,6 @@ import { mkdir, writeFile } from "node:fs/promises";
 const FRAMEWORK_ID = "framework-aicpa-trust-services-criteria";
 const DESCRIPTION_FRAMEWORK_ID = "framework-aicpa-soc2-description-criteria";
 const OWNER_ID = "person-policy-owner";
-const INDEPENDENT_APPROVER_ID = "person-independent-approver";
 const OVERSIGHT_TEAM_ID = "team-security-risk-oversight";
 const INFORMATION_SECURITY_POLICY_ID = "policy-information-security";
 const DATA_POLICY_ID = "policy-data-protection-handling";
@@ -70,7 +69,7 @@ const controls = [
     title: "Security governance",
     statement: "Management assigns security responsibilities, and a reviewer who is separate from the policy owner and control operators independently reviews the program, risks, incidents, findings, policy approvals, and overdue work at least quarterly.",
     requirements: ["CC1.1", "CC1.2", "CC1.3", "CC1.5"],
-    activity: "Assign an external independent reviewer and record quarterly oversight decisions, approvals, and actions.",
+    activity: "Assign an independent reviewer who is separate from program ownership and record quarterly oversight decisions, approvals, and actions.",
     controlType: "preventive",
     operationMode: "manual",
     frequency: "Quarterly",
@@ -963,21 +962,21 @@ export function baselineRecordFiles(effectiveDate) {
     id: OVERSIGHT_TEAM_ID,
     type: "team",
     title: "Security and Risk Oversight",
-    status: "active",
+    status: "inactive",
     purpose: "Provide independent oversight of the security program, risk register, incidents, findings, vendor and access reviews, policy changes, exercises, and overdue work. The chair must be separate from the policy owner and people who operate the controls under review.",
-    memberIds: [OWNER_ID, INDEPENDENT_APPROVER_ID],
-    chairIds: [INDEPENDENT_APPROVER_ID],
+    memberIds: [OWNER_ID],
+    chairIds: [],
     meetingCadence: calendar("month", 3, effectiveDate)
   };
   const programRepository = {
     schemaVersion: 1,
     id: "system-filegrc-program-repository",
     type: "system",
-    title: "FileGRC Program Repository",
+    title: "filegrc Program Repository",
     status: "active",
     criticality: "high",
     ownerIds: [OWNER_ID],
-    description: "The Git repository that is authoritative for FileGRC governance records, approvals, exceptions, findings, acknowledgements, evidence indexes, and their revision history.",
+    description: "The Git repository that is authoritative for filegrc governance records, approvals, exceptions, findings, acknowledgements, evidence indexes, and their revision history.",
     systemKind: "governance-system-of-record",
     environment: "Git repository",
     dataClassification: "Confidential",

package/src/index.js

@@ -10,18 +10,19 @@ const execute = promisify(execFile);
 const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
 const textExtensions = new Set(["", ".json", ".md", ".txt", ".yml", ".yaml", ".gitignore"]);
 
-export async function createFileGRC(options = {}) {
+export async function createFilegrc(options = {}) {
   const parameterConfig = JSON.parse(await readFile(join(packageRoot, "template-parameters.json"), "utf8"));
   const target = resolve(options.target ?? "filegrc-program");
   await assertWritableTarget(target, Boolean(options.force));
   if (options.force) await assertNoTemplateCollisions(target);
 
   const prompted = await resolvePromptValues(parameterConfig.parameters, options);
-  const engineVersion = await resolveFileGRCVersion(options.filegrcVersion);
+  const engineVersion = await resolveFilegrcVersion(options.filegrcVersion);
   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}`
   };
 
@@ -29,17 +30,27 @@ export async function createFileGRC(options = {}) {
   await copyTemplate(target);
   await renderTemplate(target, parameterConfig, values);
   await writeBaselineRecords(target, values.effective_date);
+  const resourceCounts = await summarizeResources(target);
 
-  if (options.install !== false) {
+  const installed = options.install !== false;
+  if (installed) {
     await run("npm", ["install", "--ignore-scripts"], target);
   } else {
     await writeMinimalLockfile(target, values.project_name, values.filegrc_version_range);
   }
-  if (!await isInsideGitWorktree(target)) await run("git", ["init"], target);
-  return { target, values, engineVersion };
+  const joinedExistingWorktree = await isInsideGitWorktree(target);
+  if (!joinedExistingWorktree) await run("git", ["init"], target);
+  return {
+    target,
+    values,
+    engineVersion,
+    resourceCounts,
+    install: installed ? "installed" : "skipped",
+    gitMode: joinedExistingWorktree ? "existing-worktree" : "initialized"
+  };
 }
 
-export async function resolveFileGRCVersion(explicitVersion) {
+export async function resolveFilegrcVersion(explicitVersion) {
   if (explicitVersion) return cleanVersion(explicitVersion);
   try {
     const { stdout } = await execute("npm", ["view", "filegrc", "version", "--json"], {
@@ -58,7 +69,9 @@ async function resolvePromptValues(parameters, options) {
   const mapped = {
     company_name: options.companyName,
     policy_owner_name: options.policyOwnerName,
-    security_contact_email: options.securityContactEmail
+    policy_owner_email: options.policyOwnerEmail,
+    security_contact_email: options.securityContactEmail,
+    timezone: options.timezone
   };
   if (options.yes) {
     mapped.company_name ??= "Example Company";
@@ -68,21 +81,29 @@ async function resolvePromptValues(parameters, options) {
   for (const key of Object.keys(mapped)) {
     if (mapped[key] !== undefined && mapped[key] !== null) mapped[key] = String(mapped[key]).trim();
   }
-  const missing = parameters.filter(({ key, required }) => required && !mapped[key]);
-  if (missing.length) {
-    if (!process.stdin.isTTY || !process.stdout.isTTY) {
-      throw new Error(`Missing required values: ${missing.map(({ key }) => key).join(", ")}`);
-    }
+  if (process.stdin.isTTY && process.stdout.isTTY) {
     const prompt = createInterface({ input: process.stdin, output: process.stdout });
     try {
-      for (const parameter of missing) {
+      for (const parameter of parameters.filter(({ required, key }) => required && !mapped[key])) {
+        const defaultValue = parameterDefault(parameter, mapped);
+        const suffix = defaultValue ? ` [${defaultValue}]` : "";
         let value = "";
-        while (!value) value = (await prompt.question(`${parameter.prompt}: `)).trim();
+        while (!value) {
+          value = (await prompt.question(`${parameter.prompt}${suffix}: `)).trim() || defaultValue;
+        }
         mapped[parameter.key] = value;
       }
     } finally {
       prompt.close();
     }
+  } else {
+    for (const parameter of parameters.filter(({ required, key }) => required && !mapped[key])) {
+      mapped[parameter.key] = parameterDefault(parameter, mapped);
+    }
+  }
+  const missing = parameters.filter(({ key, required }) => required && !mapped[key]);
+  if (missing.length) {
+    throw new Error(`Missing required values: ${missing.map(({ key }) => key).join(", ")}`);
   }
   for (const key of ["company_name", "policy_owner_name"]) {
     if (/[\u0000-\u001f\u007f]/.test(mapped[key])) {
@@ -93,12 +114,39 @@ async function resolvePromptValues(parameters, options) {
       throw new Error(`${key} cannot contain template token syntax.`);
     }
   }
-  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(mapped.security_contact_email)) {
-    throw new Error("Security contact email must be a valid email address.");
+  for (const [key, label] of [
+    ["policy_owner_email", "Policy owner email"],
+    ["security_contact_email", "Security contact email"]
+  ]) {
+    if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(mapped[key])) {
+      throw new Error(`${label} must be a valid email address.`);
+    }
   }
+  if (!isTimezone(mapped.timezone)) throw new Error("Program timezone must be a valid IANA time zone.");
   return mapped;
 }
 
+function parameterDefault(parameter, mapped) {
+  if (parameter.defaultFrom) return mapped[parameter.defaultFrom] || "";
+  if (parameter.defaultSource === "local-timezone") return localTimezone();
+  return "";
+}
+
+function localTimezone() {
+  const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+  return isTimezone(timezone) ? timezone : "UTC";
+}
+
+function isTimezone(value) {
+  if (!value) return false;
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: value }).format();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 async function assertWritableTarget(target, force) {
   try {
     if ((await lstat(target)).isSymbolicLink()) {
@@ -167,9 +215,11 @@ async function renderTemplate(target, parameterConfig, values) {
 
 async function templateDestinationPaths() {
   const template = join(packageRoot, "template");
-  return (await collectFiles(template)).map((source) => {
+  return (await collectFiles(template)).flatMap((source) => {
     const templatePath = relative(template, source);
-    return templatePath === "gitignore" ? ".gitignore" : templatePath;
+    if (templatePath === "README.md") return [];
+    if (templatePath === "WORKSPACE.md") return ["README.md"];
+    return [templatePath === "gitignore" ? ".gitignore" : templatePath];
   });
 }
 
@@ -177,7 +227,10 @@ async function copyTemplate(target) {
   const template = join(packageRoot, "template");
   for (const source of await collectFiles(template)) {
     const templatePath = relative(template, source);
-    const destinationPath = templatePath === "gitignore" ? ".gitignore" : templatePath;
+    if (templatePath === "README.md") continue;
+    const destinationPath = templatePath === "WORKSPACE.md"
+      ? "README.md"
+      : templatePath === "gitignore" ? ".gitignore" : templatePath;
     const destination = join(target, destinationPath);
     await assertNoSymlinkComponents(target, destinationPath);
     await mkdir(dirname(destination), { recursive: true });
@@ -199,16 +252,29 @@ async function collectFiles(directory) {
   return result;
 }
 
+async function summarizeResources(target) {
+  const counts = {};
+  let total = 0;
+  for (const path of await collectFiles(join(target, "data"))) {
+    if (extname(path) !== ".json") continue;
+    const record = JSON.parse(await readFile(path, "utf8"));
+    if (!record?.id || !record?.type || !record?.schemaVersion) continue;
+    total += 1;
+    counts[record.type] = (counts[record.type] || 0) + 1;
+  }
+  return { total, byType: counts };
+}
+
 async function writeMinimalLockfile(target, name, versionRange) {
   const lock = {
     name,
-    version: "0.1.0",
+    version: "0.3.0",
     lockfileVersion: 3,
     requires: true,
     packages: {
       "": {
         name,
-        version: "0.1.0",
+        version: "0.3.0",
         dependencies: { filegrc: versionRange }
       }
     }
@@ -237,7 +303,7 @@ async function run(command, args, cwd) {
 function cleanVersion(value) {
   const version = String(value ?? "").trim().replace(/^v/, "");
   if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version)) {
-    throw new Error(`Could not resolve a valid FileGRC version from "${value}".`);
+    throw new Error(`Could not resolve a valid filegrc version from "${value}".`);
   }
   return version;
 }

package/template/AGENTS.md

@@ -1,8 +1,8 @@
-# FileGRC SOC 2 Workspace Instructions
+# filegrc SOC 2 Workspace Instructions
 
 ## 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.
+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.
 
 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,11 +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 guide risk-assessment --json
 npx filegrc list person --json
+npx filegrc program-readiness --summary --json
 ```
 
-The first command lists every supported action and record type. The type guide gives the purpose, policy basis, timing, required and conditional fields, current relationship candidates, JSON location, and Markdown slots.
+`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.
 
 For a new record, generate a mutation envelope:
 
@@ -44,7 +46,7 @@ Read `data/AGENTS.md` before changing records. More specific instructions inside
 - Let the local app generate IDs from each record’s name or title. When editing JSON directly, keep IDs globally unique, human-readable, and lowercase kebab-case.
 - Use ISO 8601 dates and RFC 3339 timestamps.
 - Store relationships as resource IDs.
-- Put policies, plans, charters, procedures, meeting minutes, training, assertions, narratives, templates, and audit responses in Markdown beside their JSON records. FileGRC derives the Markdown name, so records do not contain file paths.
+- Put policies, plans, charters, procedures, meeting minutes, training, assertions, narratives, templates, and audit responses in Markdown beside their JSON records. filegrc derives the Markdown name, so records do not contain file paths.
 - Put signed forms, screenshots, third-party reports, and immutable exports behind evidence records. These files may be PDF, image, CSV, or another fixed format.
 - Never fetch an external evidence reference automatically.
 - Do not store secrets, credentials, session data, or personal data that may need to be erased from Git history.
@@ -93,7 +95,7 @@ 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, recurring obligations, event checklists, and bulk evidence preparation, then collects the initial service boundary, owner, business criticality, highest data classification, internet exposure, and optional audit objective. It creates or updates a `system` record and may create a planned `audit` record. Treat both as drafts to review against actual scope.
+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.
 
 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.
 
@@ -105,15 +107,15 @@ The generated workspace starts with the SOC 2 Security category:
 - 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 external independent reviewer
+- 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, scope, operation, and evidence match actual practice. 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.
+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. 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.
+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.
 
-## Policy work queue
+## Work Queue and Policy Events
 
 Run the same obligation planner used by the web app:
 
@@ -122,7 +124,9 @@ npx filegrc obligations --json
 npx filegrc obligations --from 2026-01-01 --through 2026-12-31 --complete --json
 ```
 
-A calendar obligation’s recurrence anchor starts its first allowed cycle. Unless `window` narrows that range, completion is allowed from the cycle start through the day before the next cycle, and the item becomes overdue on the next cycle’s first day. Use **Record work** in the obligation board, or create and link a completion atomically with:
+Work Queue includes recurring obligations, Policy Event tasks, and every other open Action Item. Create an Action Item only when follow-up from a Finding, Risk, Incident, review, test, meeting, Exception, or request needs its own assignee, deadline, and completion proof. Point `sourceResourceId` to the record that produced the task. Use that source record’s Markdown for the report and observations.
+
+A calendar obligation’s recurrence anchor starts its first allowed cycle. Unless `window` narrows that range, completion is allowed from the cycle start through the day before the next cycle, and the item becomes overdue on the next cycle’s first day. Use **Record work** in Work Queue, or create and link a completion atomically with:
 
 ```sh
 npx filegrc complete obligation-id completion-record.json
@@ -130,14 +134,14 @@ npx filegrc complete obligation-id completion-record.json
 
 Keep prior completion links because the planner matches each dated record to its own period.
 
-Event obligations are templates. Do not mark a template complete or replace it for each occurrence. Start a workflow in the obligation board or run:
+Event obligations are templates. Do not mark a template complete or replace it for each occurrence. Use Trigger Work on Step 5 or run:
 
 ```sh
 npx filegrc trigger person-started --occurred-on 2026-07-25 --subject person-new-worker --json
 npx filegrc trigger person-ended --occurred-at 2026-07-25T16:30:00-05:00 --subject person-departing-worker --json
 ```
 
-The command creates one `obligation-event` and its complete action checklist in a single validated write. Hour-based deadlines require an RFC 3339 event timestamp so an immediate or 24-hour cutoff is exact. Day-based deadlines use the event’s calendar date. Link the requested completion resources and evidence to each action item, then mark the actions done and the event complete. Every generated action has a cutoff. FileGRC applies a 30-day deadline when a custom event obligation omits one.
+Run `npx filegrc obligations` first to preview every task, owner, deadline, and requested proof for each available Policy Event. The trigger command creates one `obligation-event` and adds its full set of Action Items to the Work Queue in a single validated write. Its success output names the event, task count, task IDs, and deadlines. Hour-based deadlines require an RFC 3339 event timestamp so an immediate or 24-hour cutoff is exact. Day-based deadlines use the event’s calendar date. Link the requested completion resources and evidence to each action item, then mark the actions done and the event complete. Every generated action has a cutoff. filegrc applies a 30-day deadline when a custom event obligation omits one.
 
 Complete an event action and link its new proof in one validated write:
 
@@ -146,7 +150,7 @@ npx filegrc complete-action action-item-id completion-record.json --completed-on
 npx filegrc complete-event obligation-event-id --completed-on 2026-07-25
 ```
 
-FileGRC rejects a completion resource whose type does not match the obligation. It will close the event only after every action has its requested proof.
+filegrc rejects a completion resource whose type does not match the obligation. It will close the event only after every action has its requested proof.
 
 ## Headless Markdown
 
@@ -157,11 +161,36 @@ npx filegrc content risk-assessment risk-assessment-2026 --json
 npx filegrc content risk-assessment risk-assessment-2026 --write updated-assessment.md
 ```
 
-Run `filegrc guide <type>` to get slot names. Policies use `content`, meetings use `agenda` and `minutes`, and implicit long-form work uses `record`. FileGRC derives the path and rejects content that does not belong to the record.
+Run `filegrc guide <type>` to get slot names. Policies use `content`, meetings use `agenda` and `minutes`, and implicit long-form work uses `record`. filegrc derives the path and rejects content that does not belong to the record.
+
+## Program readiness and the candidate period
+
+Prepare the management program before creating an audit engagement:
+
+```sh
+npx filegrc program-readiness
+npx filegrc program-readiness --require-ready --summary --json
+```
+
+The Evidence Ready gate requires:
+
+1. A management goal, selected systems, criteria, and controls.
+2. Active policies with completed text, separate management approval, real approval and effective dates, and linked controls.
+3. Implemented controls with an owner, actual procedure, scope, cadence, evidence source, mappings, implementation date, and every eligible linked Work Queue schedule running.
+4. Active authoritative systems with evidence source roles, access owners, and repeatable extraction instructions in Record Markdown.
+5. A verified `test-export` or `test-capture` evidence record for each selected control family that relies on evidence from outside filegrc.
+
+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.
+
+When the gate passes, set `workspace.candidatePeriodStart` to the date reliable evidence collection begins. Do not backdate it. `candidatePeriodStart` and `candidatePeriodEnd` express management’s target. They do not establish the final report period.
+
+Maintain risk assessments and the risk register while the program operates. Complete assessments on schedule and after material changes, and add or update controls when the conclusions require a different response. Audit preparation still checks for a current, independently reviewed assessment.
+
+Record complementary customer or subservice controls after the internal control set is defined. `complementary-control.relatedControlIds` is the source of truth for those links. filegrc derives the reverse connections for Control pages and evidence packets.
 
 ## Audit preparation and evidence packets
 
-After setting a Type 1 as-of date or Type 2 period, initialize the engagement-specific management work:
+After engaging a CPA firm, create one audit record and set the firm-agreed Type 1 date or Type 2 period. Then initialize the engagement-specific management work:
 
 ```sh
 npx filegrc prepare-audit audit-2026-type-2
@@ -169,13 +198,22 @@ npx filegrc audit-readiness audit-2026-type-2
 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.
 
+Review both evidence paths against the exact firm-agreed date or period:
+
+1. filegrc Evidence consists of dated Step 5 operating records. Complete each applicable record, link it to the Controls it supports, record the result in structured fields or Markdown, and link any external artifact needed to support that result.
+2. External Evidence consists of verified `evidence` records from authoritative Systems. Confirm the source System, audit date or period, Control links, collector, verifier, and fixed attachment or approved external reference.
+
+Audit Readiness reports coverage for both paths. The packet includes the matching filegrc records and Markdown with Git history, plus External Evidence records, retained attachments, delivery indexes, and checksums.
+
 Near the end of fieldwork, link a verified fixed-format copy of the signed management representation letter to its engagement-specific document. Date it on or after the Type 1 date or Type 2 period end. A representation that is still marked for later blocks packet delivery.
 
-Catalog each authoritative source under Systems and assign its `evidenceSourceKinds`. Name the people who can access its reports and keep extraction instructions in the system's Record Markdown. For each Type 2 population, select one source system and export the exact audit period. Split a population when different systems or queries produce its items. Link a verified `population-export` evidence record that names the same source system and stores the query or report parameters, generation time, timezone, count, completeness check, and accuracy check. A zero count still requires the source export and query. A population linked to an in-scope control cannot be marked not applicable.
+Catalog each authoritative source under Systems and assign its `evidenceSourceKinds`. A third-party application is still a System because it operates controls or produces evidence. Create a separate Vendor for its provider and connect the System through `vendorId`; keep contracts, due diligence, and supplier risk on the Vendor. Name the people who can access system reports and keep extraction instructions in the System's Record Markdown. For each Type 2 population, select one source system and export the exact audit period. Split a population when different systems or queries produce its items. Link a verified `population-export` evidence record that names the same source system and stores the query or report parameters, generation time, timezone, count, completeness check, and accuracy check. A zero count still requires the source export and query. A population linked to an in-scope control cannot be marked not applicable.
 
-Every evidence record names its collector. Verified evidence also names its verifier and verification date. Use `sourceSystemId` for system exports, `sourceResourceIds` for FileGRC records, and `sourceCommit` to bind the evidence to repository state.
+Every evidence record names its collector. Verified evidence also names its verifier and verification date. Use `sourceSystemId` for system exports, `sourceResourceIds` for filegrc records, and `sourceCommit` to bind the evidence to repository state.
 
 Preview coverage before writing output:
 
@@ -185,21 +223,23 @@ npx filegrc evidence-packet --audit audit-2026-type-2
 npx filegrc evidence-packet --audit audit-2026-type-2 --preview --require-ready
 ```
 
-The packet includes records explicitly related to the selected engagement, its systems, controls, criteria, policies, evidence, and dependencies. It does not include unrelated dated records from the workspace. A Type 2 packet adds period operating records, recurring obligation occurrences, event workflows, and management population reconciliations. Output includes a control matrix, source-system index, external-evidence delivery index, population index, evidence index, committed historical source versions, and SHA-256 checksums. Output under `.filegrc/evidence-packets/` is derived and must not be hand-edited or committed.
+The packet includes records explicitly related to the selected engagement, its systems, controls, criteria, policies, evidence, and dependencies. It does not include unrelated dated records from the workspace. A Type 2 packet adds filegrc Evidence, recurring obligation occurrences, event workflows, and management population reconciliations. Output includes a control matrix with separate filegrc Evidence and External Evidence columns, source-system index, external-evidence delivery index, population index, evidence index, committed historical source versions, and SHA-256 checksums. Output under `.filegrc/evidence-packets/` is derived and must not be hand-edited or committed.
 
-Treat a packet as ready for management delivery only when its status is `delivery-ready`, its review list is clear, and its manifest names a clean Git revision. This means FileGRC's management checks passed. It does not mean the engagement team found the evidence sufficient or appropriate. The generator copies raw records, Markdown, and local fixed attachments. It never fetches external references. Reconcile `external-evidence-index.csv` to the auditor portal or other approved delivery system before telling the engagement team that submission is complete.
+Treat a packet as ready for management delivery only when its status is `delivery-ready`, its review list is clear, and its manifest names a clean Git revision. This means filegrc's management checks passed. It does not mean the engagement team found the evidence sufficient or appropriate. The generator copies raw records, Markdown, and local fixed attachments. It never fetches external references. Reconcile `external-evidence-index.csv` to the auditor portal or other approved delivery system before telling the engagement team that submission is complete.
 
-Link a control test to its `audit-population` record when sampling applies. Link item-level sample evidence separately. Management owns population completeness and accuracy. The auditor owns sample selection, independent testing, exception evaluation, and the report opinion. The auditor or publisher also supplies the authoritative criteria and examination guidance. FileGRC stores references and orientation text, not licensed criteria.
+Link a control test to its `audit-population` record when sampling applies. Link item-level sample evidence separately. Management owns population completeness and accuracy. The auditor owns sample selection, independent testing, exception evaluation, and the report opinion. The auditor or publisher also supplies the authoritative criteria and examination guidance. filegrc stores references and orientation text, not licensed criteria.
 
 ## Content and approvals
 
-The seed policy owner is {{policy_owner_name}} and the reporting address is {{security_contact_email}}. Replace ownership or contacts when responsibilities change.
+The seed policy owner is {{policy_owner_name}} at {{policy_owner_email}}, and the security reporting address is {{security_contact_email}}. Replace ownership or contacts when responsibilities change.
+
+Appoint an independent management reviewer during policy review, not as a condition of defining the service boundary. The reviewer must be separate from the policy owner and able to challenge the owner’s decisions. Most organizations assign another internal leader or manager. An external reviewer is also allowed, and a one-person company needs one because no second internal person is available. The reviewer chairs Security and Risk Oversight and approves policies and governed documents.
 
-The starter requires an external independent reviewer for SOC 2 oversight. This person must be separate from the policy owner and must not operate the controls they review. They chair Security and Risk Oversight and approve policies and governed documents. A one-person company must appoint a qualified person outside the company before approving the program. Do not use the audit firm for management or approval work without first confirming the firm's independence requirements.
+The management reviewer and CPA auditor are different roles. Do not assign the CPA firm management or approval work without first confirming the firm's independence requirements.
 
 Policy and training attestations must identify the exact Git revision of the content that a person acknowledged. Store signatures as evidence attachments and link their evidence IDs from the attestation.
 
-Committee and risk meeting minutes are `meeting` resources with a primary Markdown companion. An optional `-agenda.md` companion holds the agenda. Record attendees, decisions, risks discussed, and action item IDs. Keep action tracking in `action-item` records.
+Committee and risk meeting minutes are `meeting` resources with a primary Markdown companion. An optional `-agenda.md` companion holds the agenda. Record attendees, decisions, and risks discussed on the Meeting. When follow-up needs separate tracking, create an `action-item` whose `sourceResourceId` points to the Meeting.
 
 ## Audit evidence