create-filegrc 0.1.0

package/src/index.js

@@ -0,0 +1,252 @@
+import { execFile } from "node:child_process";
+import { cp, lstat, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+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";
+
+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 = {}) {
+  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 values = {
+    ...prompted,
+    effective_date: options.effectiveDate ?? new Date().toISOString().slice(0, 10),
+    project_name: normalizePackageName(basename(target)),
+    filegrc_version_range: `^${engineVersion}`
+  };
+
+  await mkdir(target, { recursive: true });
+  await copyTemplate(target);
+  await renderTemplate(target, parameterConfig, values);
+  await writeBaselineRecords(target, values.effective_date);
+
+  if (options.install !== false) {
+    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 };
+}
+
+export async function resolveFileGRCVersion(explicitVersion) {
+  if (explicitVersion) return cleanVersion(explicitVersion);
+  try {
+    const { stdout } = await execute("npm", ["view", "filegrc", "version", "--json"], {
+      timeout: 15_000,
+      maxBuffer: 100_000
+    });
+    const parsed = JSON.parse(stdout);
+    return cleanVersion(Array.isArray(parsed) ? parsed.at(-1) : parsed);
+  } catch {
+    const ownPackage = JSON.parse(await readFile(join(packageRoot, "package.json"), "utf8"));
+    return cleanVersion(ownPackage.version);
+  }
+}
+
+async function resolvePromptValues(parameters, options) {
+  const mapped = {
+    company_name: options.companyName,
+    policy_owner_name: options.policyOwnerName,
+    security_contact_email: options.securityContactEmail
+  };
+  if (options.yes) {
+    mapped.company_name ??= "Example Company";
+    mapped.policy_owner_name ??= "Security Owner";
+    mapped.security_contact_email ??= "security@example.com";
+  }
+  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(", ")}`);
+    }
+    const prompt = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+      for (const parameter of missing) {
+        let value = "";
+        while (!value) value = (await prompt.question(`${parameter.prompt}: `)).trim();
+        mapped[parameter.key] = value;
+      }
+    } finally {
+      prompt.close();
+    }
+  }
+  for (const key of ["company_name", "policy_owner_name"]) {
+    if (/[\u0000-\u001f\u007f]/.test(mapped[key])) {
+      throw new Error(`${key} must be a single line without control characters.`);
+    }
+    if (mapped[key].length > 200) throw new Error(`${key} must be 200 characters or fewer.`);
+    if (/\{\{[a-z0-9_]+\}\}/.test(mapped[key])) {
+      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.");
+  }
+  return mapped;
+}
+
+async function assertWritableTarget(target, force) {
+  try {
+    if ((await lstat(target)).isSymbolicLink()) {
+      throw new Error(`Target directory must not be a symbolic link: ${target}.`);
+    }
+    const items = await readdir(target);
+    if (items.length && !force) {
+      throw new Error(`Target directory is not empty: ${target}. Pass --force to add files without overwriting existing paths.`);
+    }
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+}
+
+async function assertNoTemplateCollisions(target) {
+  const collisions = [];
+  for (const destinationPath of [...await templateDestinationPaths(), ...baselineRecordPaths()]) {
+    await assertNoSymlinkComponents(target, destinationPath);
+    try {
+      await lstat(join(target, destinationPath));
+      collisions.push(destinationPath);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+  }
+  if (collisions.length) {
+    throw new Error(`Target contains files create-filegrc would overwrite: ${collisions.slice(0, 5).join(", ")}.`);
+  }
+}
+
+async function assertNoSymlinkComponents(target, relativePath) {
+  let current = target;
+  for (const segment of relativePath.split(/[\\/]/).filter(Boolean)) {
+    current = join(current, segment);
+    try {
+      if ((await lstat(current)).isSymbolicLink()) {
+        throw new Error(`Target contains a symbolic link at ${relative(target, current)}.`);
+      }
+    } catch (error) {
+      if (error.code === "ENOENT") return;
+      throw error;
+    }
+  }
+}
+
+async function renderTemplate(target, parameterConfig, values) {
+  const declared = new Set([
+    ...parameterConfig.parameters.map(({ key }) => key),
+    ...parameterConfig.generated.map(({ key }) => key)
+  ]);
+  const files = (await templateDestinationPaths()).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) => {
+      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 unresolved = /\{\{([a-z0-9_]+)\}\}/.exec(source);
+    if (unresolved) throw new Error(`Unresolved template token "{{${unresolved[1]}}}" in ${path}`);
+    await writeFile(path, source, "utf8");
+  }
+}
+
+async function templateDestinationPaths() {
+  const template = join(packageRoot, "template");
+  return (await collectFiles(template)).map((source) => {
+    const templatePath = relative(template, source);
+    return templatePath === "gitignore" ? ".gitignore" : templatePath;
+  });
+}
+
+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;
+    const destination = join(target, destinationPath);
+    await assertNoSymlinkComponents(target, destinationPath);
+    await mkdir(dirname(destination), { recursive: true });
+    await cp(source, destination, {
+      force: false,
+      errorOnExist: true,
+      preserveTimestamps: false
+    });
+  }
+}
+
+async function collectFiles(directory) {
+  const result = [];
+  for (const item of await readdir(directory, { withFileTypes: true })) {
+    const path = join(directory, item.name);
+    if (item.isDirectory()) result.push(...await collectFiles(path));
+    else if (item.isFile()) result.push(path);
+  }
+  return result;
+}
+
+async function writeMinimalLockfile(target, name, versionRange) {
+  const lock = {
+    name,
+    version: "0.1.0",
+    lockfileVersion: 3,
+    requires: true,
+    packages: {
+      "": {
+        name,
+        version: "0.1.0",
+        dependencies: { filegrc: versionRange }
+      }
+    }
+  };
+  await writeFile(join(target, "package-lock.json"), `${JSON.stringify(lock, null, 2)}\n`, "utf8");
+}
+
+async function isInsideGitWorktree(target) {
+  try {
+    await execute("git", ["rev-parse", "--is-inside-work-tree"], { cwd: target });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function run(command, args, cwd) {
+  try {
+    return await execute(command, args, { cwd, maxBuffer: 10_000_000 });
+  } catch (error) {
+    const detail = error.stderr?.trim() || error.stdout?.trim() || error.message;
+    throw new Error(`${command} ${args.join(" ")} failed: ${detail}`);
+  }
+}
+
+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}".`);
+  }
+  return version;
+}
+
+function normalizePackageName(value) {
+  const normalized = value.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+  return normalized || "filegrc-program";
+}
+
+function jsonStringContents(value) {
+  return JSON.stringify(String(value)).slice(1, -1);
+}

package/template/AGENTS.md

@@ -0,0 +1,227 @@
+# 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.
+
+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.
+
+## Agent quick start
+
+Do not guess a resource type, field name, enum value, relationship, or file path. Start every unfamiliar task with the installed model:
+
+```sh
+npx filegrc guide --json
+npx filegrc guide risk-assessment --json
+npx filegrc list person --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.
+
+For a new record, generate a mutation envelope:
+
+```sh
+npx filegrc scaffold risk-assessment --title "2026 Annual Risk Assessment" > /tmp/risk-assessment.json
+```
+
+The scaffold contains `{ "record": ..., "content": ... }`, which is the same payload shape used by the renderer. Null values and empty required arrays are deliberate prompts. Replace all of them with facts before creation:
+
+```sh
+npx filegrc create /tmp/risk-assessment.json
+npx filegrc validate --json
+git diff --check
+git diff
+```
+
+Read `data/AGENTS.md` before changing records. More specific instructions inside high-risk collections apply in addition to that file.
+
+## Working rules
+
+- Read `README.md` and run `npm run validate` before broad changes.
+- Treat `data/` as the source of truth. Do not hand-edit `.filegrc/` output.
+- Use UTF-8 JSON for structured records and Markdown for long-form work.
+- Keep one resource in each JSON file.
+- 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 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.
+- Keep the editable local server on loopback or behind trusted authentication. Use the read-only static build for audit sharing.
+
+## Git is the audit trail
+
+Git supplies file authors, commit timestamps, messages, diffs, and revisions. Do not add fields such as `createdAt`, `updatedAt`, `createdBy`, `updatedBy`, or a second change log.
+
+Domain events still need explicit dates. Keep values such as `occurredOn`, `approvedOn`, `reviewedOn`, `completedOn`, and audit-period dates in their records.
+
+Make focused commits with messages that explain the reason for the change. The engine never creates commits automatically. Review the workspace diff, then use the commit action on Repository or the Git CLI. The renderer validates the workspace and requires an explicit message before it creates a commit.
+
+Pull before starting work when other people or agents may have changed the repository. Without a remote, the browser's Repository page creates a local commit and hides synchronization actions. With a remote, it pulls with rebase, refuses to pull over uncommitted files, and pushes immediately after it creates a commit. Agents and terminal users own Git synchronization and should run `git pull --rebase`, `git commit`, and `git push` directly. Do not create merge commits for routine synchronization.
+
+Do not rewrite or remove committed records that explain prior audit periods. Close or retire them. Delete only mistakes and uncommitted drafts.
+
+## Data model
+
+`data/workspace.json` selects the model through `dataModelVersion`. The installed `filegrc` package owns the authoritative model. Do not copy or invent a local schema.
+
+Run these commands when working with records:
+
+```sh
+npm run validate
+npx filegrc guide --json
+npx filegrc guide risk
+npx filegrc list risk --json
+npx filegrc get risk-example
+npx filegrc get risk-example --mutation
+npx filegrc references risk-example --json
+npx filegrc describe risk
+npx filegrc search "access review"
+npm run serve
+```
+
+Prefer existing fields. Put organization-specific values under `extensions` with a namespace owned by {{company_name}}. Add structure only when validation, filtering, relationships, due dates, or audit completeness need it. Variable procedures, interviews, observations, rationale, and detailed results belong in the record's Markdown companion.
+
+Never change a resource ID after it is committed. Create a replacement and link the records if identity truly changes.
+
+The local app keeps IDs out of the guided form, generates them during creation, and leaves them unchanged when a record is renamed. It presents the core model fields and relationship pickers. Use its advanced JSON section for optional fields and extensions. It rejects a save if the source file changed after the editor opened, so reload and reapply the change instead of overwriting newer work.
+
+Headless agents get the same protection by exporting an edit payload with `filegrc get RESOURCE_ID --mutation` and passing that file to `filegrc update`.
+
+## Renderer settings and onboarding
+
+`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.
+
+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 external independent reviewer
+- 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.
+
+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.
+
+## Policy work queue
+
+Run the same obligation planner used by the web app:
+
+```sh
+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:
+
+```sh
+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:
+
+```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.
+
+Complete an event action and link its new proof in one validated write:
+
+```sh
+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
+```
+
+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
+
+Create and update JSON plus Markdown in one mutation envelope when practical. You can also inspect or replace a companion directly:
+
+```sh
+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.
+
+## Audit preparation and evidence packets
+
+After setting a Type 1 as-of date or Type 2 period, initialize the engagement-specific management work:
+
+```sh
+npx filegrc prepare-audit audit-2026-type-2
+npx filegrc audit-readiness audit-2026-type-2
+npx filegrc audit-readiness audit-2026-type-2 --require-ready --json
+```
+
+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.
+
+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.
+
+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:
+
+```sh
+npx filegrc evidence-packet --audit audit-2026-type-2 --preview --json
+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.
+
+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.
+
+## 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 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.
+
+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.
+
+## Audit evidence
+
+A rendered-page evidence capture must identify:
+
+- The route and filters shown
+- The audit or evidence period
+- The exact Git commit
+- The capture timestamp and method
+- The source resource IDs
+- The screenshot or fixed export
+
+Commit the evidence record and attachment together. Do not claim that a current page proves a prior period unless it is rendered from or bound to the correct revision.
+
+## Validation
+
+After substantive edits:
+
+1. Run `npm run validate`.
+2. Review JSON and Markdown diffs.
+3. Check every new relationship and attachment.
+4. Confirm dates describe the business event, not the edit time.
+5. Run `npm run build` when producing a read-only audit view.
+
+Do not loosen validation to make a bad record pass. Fix the record or update the installed engine through its normal versioned model process.

package/template/README.md

@@ -0,0 +1,102 @@
+# FileGRC
+
+Run a SOC 2 program as files in Git.
+
+FileGRC gives a founder-led engineering team one place to adopt policies, track recurring compliance work, respond to company events, and prepare an audit. JSON holds structured records, Markdown holds long-form work, and Git supplies the change history.
+
+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.
+
+![FileGRC SOC 2 program overview](docs/filegrc-home.png)
+
+## 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.
+- The obligation board turns policy timing into upcoming, due, and overdue work.
+- Event checklists cover hiring, departures, vendor changes, incidents, and other policy triggers.
+- Audit Readiness says what management work, source-system exports, and evidence are still missing.
+- 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.
+
+```sh
+npx create-filegrc@latest company-grc
+cd company-grc
+npm run validate
+npm run serve
+```
+
+Setup asks for the company name, the initial policy owner, and a security contact email. It initializes Git when needed. The first local run then helps define the service boundary, an independent approver, and an optional audit goal.
+
+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.
+
+## How it works
+
+1. Add or edit compliance artifacts under `data/`.
+2. FileGRC validates relationships, renders the current program, and calculates policy work.
+3. Commit focused changes with a message that explains why the records changed.
+4. Git preserves the author, time, message, diff, and prior version.
+5. For an audit, define the Type 1 date or Type 2 period and generate an evidence packet from the selected revision.
+
+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.
+
+## Run the program
+
+Use Overview to follow the audit chain: scope, criteria, policies, controls, operation, and audit. The sidebar follows the same order.
+
+Use Obligation Board for recurring work and event checklists. Each item shows its allowed completion window and overdue cutoff, based on the policy that created it. Link a dated completion record and evidence to close the occurrence.
+
+Use the resource pages to maintain systems, people, vendors, risks, controls, tests, incidents, training, meetings, and 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.
+
+Agents use the same logic headlessly:
+
+```sh
+npx filegrc guide risk-assessment --json
+npx filegrc scaffold risk-assessment --title "2026 Annual Risk Assessment"
+npx filegrc list risk --json
+npx filegrc obligations --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"
+```
+
+`guide` reports the policy context, timing, required fields, valid values, relationship candidates, and Markdown locations for every resource type. `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.
+
+## Prepare the audit
+
+Record the audit firm, scope, and exact date or period. Audit Readiness then checks management-owned preparation, including the system description, assertion, policy and control state, source systems, evidence, and Type 2 populations.
+
+![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 packages the selected records, Markdown, fixed attachments, historical versions, indexes, and SHA-256 checksums.
+
+```sh
+npx filegrc prepare-audit audit-id
+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.
+
+## 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.
+
+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.
+
+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.
+
+## Repository safety
+
+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. Read `AGENTS.md` before broad record changes or automation work.