open-agreements 0.2.0 → 0.2.2

package/skills/delaware-franchise-tax/reference/ecorp-portal-playwright-notes.md

@@ -0,0 +1,136 @@
+# Delaware eCorp Portal — Playwright Automation Notes
+
+## Setup
+
+### Launch Chrome with remote debugging
+
+```bash
+# Must quit Chrome first, then relaunch with debug port
+osascript -e 'tell application "Google Chrome" to quit'
+sleep 2
+/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
+  --remote-debugging-port=9222 \
+  --user-data-dir=/tmp/chrome-debug-profile &
+```
+
+### Connect via Playwright (CDP)
+
+```python
+NODE_OPTIONS='--no-deprecation' uv run python3 << 'PYEOF'
+from playwright.sync_api import sync_playwright
+with sync_playwright() as p:
+    browser = p.chromium.connect_over_cdp("http://localhost:9222")
+    ctx = browser.contexts[0]
+    page = ctx.pages[0]
+PYEOF
+```
+
+## Fixes & Gotchas
+
+### 1. Readonly "Total Issued Shares" field
+- `gridStock_ctl02_txtIssuedShares` is **readonly** — it's auto-summed from per-class fields
+- Fill the per-class field instead: `gridStock_ctl02_gridStockDetails_ctl02_txtIssuedShares`
+- This populates the readonly total automatically on recalculate
+
+### 2. Asset Date field mangles input with Playwright .fill()/.type()
+- The date field has a mask/formatter that garbles Playwright keyboard input
+- **Fix**: Use JavaScript to set the value directly:
+  ```python
+  page.evaluate('''
+      const el = document.getElementById('ctl00_ContentPlaceHolder1_gridStock_ctl02_txtAssetDate');
+      el.value = '12/31/2025';
+      el.dispatchEvent(new Event('change', { bubbles: true }));
+  ''')
+  ```
+- The portal requires asset date == fiscal year end date, or it ignores gross assets
+
+### 3. APVC method activation
+- Portal defaults to Authorized Shares method ($85,165 for 10M shares)
+- To get APVC: fill issued shares + gross assets + correct asset date, then click "Recalculate Tax"
+- If asset date doesn't match fiscal year end, recalculate silently stays on Authorized Shares
+
+### 4. ASP.NET ViewState breaks on back-navigation
+- Never use `page.go_back()` — the ViewState expires and you get a server error
+- Always start fresh from the login page: `https://icis.corp.delaware.gov/ecorp/logintax.aspx`
+
+### 5. Postback links (2024 "File Amended Annual Report")
+- The link is `javascript:__doPostBack(...)`, not a real URL
+- Can't open in a new tab via href — must execute on the page
+- Use: `page.evaluate("__doPostBack('ctl00$ContentPlaceHolder1$lnkPrevAR','')")`
+
+### 6. CAPTCHA
+- Field: `#ctl00_ContentPlaceHolder1_ecorpCaptcha1_txtCaptcha`
+- Image: `#ctl00_ContentPlaceHolder1_ecorpCaptcha1_captchaImage` (NOT `img[src*='Captcha']`)
+- Case-insensitive in practice (all caps in image)
+- Screenshot cropping can be unreliable — fetch the CAPTCHA image bytes via JS `fetch()` on `img.src` as fallback
+
+### 7. Key field selectors
+| Field | Selector ID (after ctl00_ContentPlaceHolder1_) |
+|-------|------------------------------------------------|
+| File number | txtPrimaryFileNo |
+| CAPTCHA | ecorpCaptcha1_txtCaptcha |
+| Continue button | btnContinue |
+| Issued shares (per-class) | gridStock_ctl02_gridStockDetails_ctl02_txtIssuedShares |
+| Issued shares (total, readonly) | gridStock_ctl02_txtIssuedShares |
+| Gross assets | gridStock_ctl02_txtGrossAsset |
+| Asset date | gridStock_ctl02_txtAssetDate |
+| Fiscal year end | txtFiscalYearEndYear |
+| Recalculate button | btnRecalucation (note: typo in portal) |
+| Continue Filing button | btnProceedPayment |
+| Enter Directors button | btnDisplayDirectorForm |
+| Nature of Business | ddlBusinessNatures |
+
+### 8. State dropdowns use abbreviations (NY, WA, etc.)
+- All state dropdowns (`drpHidePrincipal`, `drpHideOfficer`, `drpHideAuthor`, `drpDirectorStatesN`) use 2-letter state codes
+- Use `page.select_option("#drpHidePrincipal", value="NY")` — NOT `label="New York"`
+
+### 9. Director form fields (inline, not popup)
+- Click `#btnDisplayDirectorForm` to reveal director rows
+- **CRITICAL**: Director names have THREE separate fields per director:
+  - `txtDirectorName{N}` = **first name only** (NOT full name!)
+  - `txtMiddleName{N}` = middle name/initial
+  - `txtLastName{N}` = last name (REQUIRED — validation fails without it)
+- Other fields: `txtDirectorAddress{N}`, `txtDirectorCity{N}`, `drpDirectorStates{N}`, `txtDirectorZip{N}`, `drpDirectorCountry{N}`
+- Numbered 1–N based on `txtTotalNumOfDirectors`
+- All use simple IDs (no ASP.NET prefix)
+
+### 10. Tax result label IDs (different from what you'd expect)
+| Label | Selector ID (after ctl00_ContentPlaceHolder1_) |
+|-------|------------------------------------------------|
+| Franchise Tax | lblFranchisetaxData |
+| Penalty | lblPenaltyData |
+| Interest | lblMonthlyIntrestData |
+| Filing Fee | lblAnnualFilingDta |
+| Credit | lblPreviousData |
+| Prepaid | lblPrepaidPaymentData |
+| **Total Due** | **lblAmountDue** |
+
+### 11. Officer and Authorization address fields
+| Section | Street | City | State | Zip |
+|---------|--------|------|-------|-----|
+| Principal | txtStreetPrincipal | txtCityPrincipal | drpHidePrincipal | txtZipPrincipal |
+| Officer | txtStreetOfficer | txtCityOfficer | drpHideOfficer | txtZipOfficer |
+| Auth | txtStreetAuthorization | txtCityAuthorization | drpHideAuthor | txtZipAuthorization |
+
+### 12. Session/eId behavior
+- Dashboard URL needs `eId` parameter from login — can't bookmark dashboard directly
+- **BUT**: Cmd+Back (browser history) in a new tab CAN get back to dashboard within the same session
+- Each login generates a unique eId; session cookies are shared across tabs
+
+### 13. T&C checkbox required before Continue Filing
+- Must check `#ctl00_ContentPlaceHolder1_chkCertify` before clicking Continue Filing
+- Validation error: "Authorization: Please check the box to confirm that you have read the Terms and Conditions"
+
+### 14. Confirmation page — save BEFORE navigating away
+- **"Once you leave this screen, you will no longer be able to obtain a confirmation copy"**
+- **PDF download**: `downloadConfirmation()` → opens `DownLoadConfirmation.ashx?srNo=...&fileNo=...`
+  - Triggers a file download, NOT a page navigation — Playwright will throw "Download is starting" error (that's OK, the file downloads)
+- **Email confirmation**: `openARemail()` → opens `Email.aspx?srNo=...` popup
+  - Fill `#txtEmailAddress` and `#txtVerifyEmailAddress`, click `#btnEmail`
+  - Response: "Your e-mail request has been received. Please allow 48 hours."
+- Service Request Number is in the URL: `?srNo=XXXXXXXXXXX`
+
+### 15. Deprecation warning
+- `[DEP0169] url.parse() behavior is not standardized` comes from Playwright's Node.js internals
+- Harmless — Playwright uses `url.parse()` in its server; fix is upstream (Playwright issue)
+- Suppress with: `NODE_OPTIONS='--no-deprecation'` env var

package/skills/edit-docx-agreement/CONNECTORS.md

@@ -0,0 +1,20 @@
+# Connectors
+
+## OpenAgreements (for template filling)
+
+Use the standard OpenAgreements connectors (remote MCP or local CLI) for fill operations.
+See https://github.com/open-agreements/open-agreements/blob/main/skills/open-agreements/CONNECTORS.md for details.
+
+## Safe Docx MCP (for surgical DOCX editing)
+
+Safe Docx is a **separate MCP server** that must be configured independently.
+It is not part of the OpenAgreements skill set.
+
+The user must have Safe Docx MCP already set up in their agent environment.
+If Safe Docx tools are not available, instruct the user to:
+
+1. Visit https://github.com/UseJunior/safe-docx for setup instructions
+2. Configure the Safe Docx MCP server in their agent's MCP settings
+3. Restart their agent session
+
+Do not instruct the agent to download or install packages at runtime.

package/skills/edit-docx-agreement/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: edit-docx-agreement
+description: >-
+  Make bespoke edits to a DOCX agreement generated by OpenAgreements (or any existing DOCX),
+  using Safe Docx MCP tools for surgical, formatting-preserving edits and tracked-changes outputs.
+license: MIT
+compatibility: >-
+  Works with any agent. Requires a separately configured Safe Docx MCP server for document editing.
+  OpenAgreements fill capabilities require the OpenAgreements remote MCP or local CLI.
+metadata:
+  author: open-agreements
+  version: "0.2.0"
+---
+
+# edit-docx-agreement
+
+Use this skill when a user asks for **custom edits that are not exposed as template fields** in an OpenAgreements-generated (or any existing) DOCX agreement.
+
+> **Interactivity note**: Always ask the user for missing inputs (file path, change intent, output preferences).
+
+## Security model
+
+This skill bridges two separate systems:
+- **OpenAgreements** (remote MCP or local CLI) — for template filling. Follows the OpenAgreements zero-download security model.
+- **Safe Docx** (local MCP server) — for surgical DOCX editing. Requires separate setup. This is **not** part of the OpenAgreements skill set and has its own trust/security model.
+
+The agent must have Safe Docx MCP tools available to perform edits. If Safe Docx tools are not detected, inform the user and provide setup guidance (see Connectors).
+
+## Decision rule: refill vs edit vs both
+
+1. **Field-only changes** (e.g., party name, date, amount, valuation cap):
+   Re-run OpenAgreements `fill_template` with the updated field values. No Safe Docx needed.
+
+2. **Boilerplate-only changes** (e.g., custom clause, modified standard language):
+   Use Safe Docx MCP tools to surgically edit the existing DOCX.
+
+3. **Mixed changes** (field updates + bespoke edits):
+   Re-fill via OpenAgreements first (to get a clean base with updated fields), save the output locally, then use Safe Docx to apply bespoke edits on the fresh file.
+
+## Execution
+
+### Step 0: Confirm you have a local .docx file path
+
+- If OpenAgreements was run via remote MCP, the fill response returns a download URL (with `expires_at`). Save the DOCX to a local path immediately.
+- If the download link has expired, re-run `fill_template` to get a fresh URL.
+- If OpenAgreements was run via local CLI, use the output file path directly.
+
+### Step 1: Verify Safe Docx MCP is available
+
+Check whether Safe Docx tools (e.g., `read_file`, `replace_text`, `apply_plan`) are available in the current session.
+
+- **If available**: proceed to Step 2.
+- **If not available**: inform the user that Safe Docx MCP is required for bespoke edits and provide setup instructions from the Connectors file. Stop here until the user configures it.
+
+### Step 2: Apply the decision rule
+
+Follow the routing logic above (field-only / boilerplate-only / mixed).
+
+For Safe Docx edits:
+- Use `read_file` to locate target paragraphs
+- Use `replace_text` or `insert_paragraph` for surgical changes
+- Use `apply_plan` for batch edits (fails safely if any step is invalid)
+- Re-read edited paragraphs to verify changes
+
+### Step 3: Deliver reviewable outputs
+
+Use Safe Docx `download` to save:
+- A **tracked-changes** DOCX for legal review
+- A **clean** DOCX for signing (optional but recommended)
+
+Summarize edits for the user (paragraph IDs, before/after text).
+
+## Licensing note
+
+Some templates (notably YC SAFEs) are licensed under CC-BY-ND-4.0. You can fill them for your own use but must not redistribute modified versions of the template itself. The filled output may constitute an "adapted work" — do not redistribute your filled output publicly without reviewing the license terms. See `docs/licensing.md` for details.
+
+This tool does not provide legal advice — consult an attorney.

package/skills/employment-contract/SKILL.md

@@ -155,3 +155,12 @@ Use `list_templates` (MCP) or `list --json` (CLI) for the latest inventory and f
 - OpenAgreements employment templates are licensed under CC-BY-4.0
 - These templates are designed for US at-will employment — state-specific laws may apply
 - This tool does not provide legal advice — consult an attorney
+
+## Bespoke edits (beyond template fields)
+
+If you need to edit boilerplate or add custom language that is not exposed as a template field,
+use the `edit-docx-agreement` skill to surgically edit the generated DOCX and produce a
+tracked-changes output for review. This requires a separately configured Safe Docx MCP server.
+
+Note: templates licensed under CC-BY-ND-4.0 (e.g., YC SAFEs) can be filled for your own use
+but must not be redistributed in modified form.

package/skills/iso-27001-evidence-collection/CONNECTORS.md

@@ -0,0 +1,23 @@
+# Connectors
+
+## How tool references work
+
+This skill uses `~~category` placeholders for optional integrations. The skill works without any connectors configured — they enhance the experience when available.
+
+## Connectors for this skill
+
+| Category | Placeholder | Recommended server | Other options |
+|----------|-------------|-------------------|---------------|
+| Compliance data | `~~compliance` | Compliance MCP server (planned — not yet available) | Local `compliance/` directory files |
+
+### Local compliance data (current default)
+
+If the `compliance/` directory exists with evidence status files, the skill reads those directly. No MCP server needed — just ensure evidence files in `compliance/evidence/*.md` are up to date.
+
+### Compliance MCP server (planned)
+
+A dedicated compliance MCP server with automated gap detection and evidence freshness tracking is planned but not yet available. When released, it will be installable as a standard MCP server. Until then, the skill operates in local-data or reference-only mode.
+
+### Fallback: Reference only
+
+Without any connector, the skill uses embedded checklists and CLI command reference. No organization-specific evidence status is available in this mode.

package/skills/iso-27001-evidence-collection/SKILL.md

@@ -0,0 +1,300 @@
+---
+name: iso-27001-evidence-collection
+description: >-
+  Collect, organize, and validate evidence for ISO 27001 and SOC 2 audits.
+  API-first approach with CLI commands for major cloud platforms. Produces
+  timestamped, auditor-ready evidence packages.
+license: MIT
+compatibility: >-
+  Works with any AI agent. Enhanced with compliance MCP server for automated
+  gap detection. Falls back to embedded checklists when no live data available.
+metadata:
+  author: open-agreements
+  version: "0.1.0"
+  frameworks:
+    - ISO 27001:2022
+    - SOC 2 Type II
+    - NIST SP 800-53 Rev 5
+---
+
+# ISO 27001 Evidence Collection
+
+Systematically collect audit evidence for ISO 27001:2022 and SOC 2. This skill provides API-first evidence collection commands, organizes evidence by control, and validates completeness before auditor review.
+
+## Security Model
+
+- **No scripts executed** — this skill is markdown-only procedural guidance
+- **No secrets required** — works with reference checklists; CLI commands use existing local credentials
+- **Evidence stays local** — all outputs go to the local filesystem
+- **IP-clean** — references NIST SP 800-53 (public domain); ISO controls cited by section ID only
+
+## When to Use
+
+Activate this skill when:
+
+1. **Preparing evidence package for external audit** — 2-4 weeks before auditor arrives
+2. **Quarterly evidence refresh** — update evidence that has aged beyond the audit window
+3. **After remediation** — collect evidence proving a finding has been fixed
+4. **New system onboarding** — establish baseline evidence for a newly in-scope system
+5. **Evidence gap analysis** — identify what's missing before the audit
+
+Do NOT use for:
+- Running the internal audit itself — use `iso-27001-internal-audit`
+- SOC 2-only readiness assessment — use `soc2-readiness`
+- Interpreting audit findings — use the internal audit skill
+
+## Core Concepts
+
+### Evidence Hierarchy (Best to Worst)
+
+| Rank | Type | Example | Why Better |
+|------|------|---------|------------|
+| 1 | **API export (JSON/CSV)** | `gcloud iam service-accounts list --format=json` | Timestamped, tamper-evident, reproducible |
+| 2 | **System-generated report** | SOC 2 report from vendor, SIEM export | Authoritative source, includes metadata |
+| 3 | **Configuration export** | Terraform state, policy JSON | Shows intended state, version-controlled |
+| 4 | **Screenshot with system clock** | `screencapture -x ~/evidence/...` | Visual proof, but harder to validate |
+| 5 | **Manual attestation** | Signed statement by responsible person | Last resort, requires corroboration |
+
+### Evidence Freshness Requirements
+
+| Evidence Type | Max Age | Refresh Cadence |
+|---------------|---------|-----------------|
+| Access lists | 90 days | Quarterly |
+| Vulnerability scans | 30 days | Monthly |
+| Configuration exports | 90 days | Quarterly |
+| Training records | 12 months | Annual |
+| Penetration test | 12 months | Annual |
+| Policy documents | 12 months | Annual review |
+| Incident records | Audit period | Continuous |
+| Risk assessment | 12 months | Annual + on change |
+
+### Evidence Naming Convention
+
+```
+{control_id}_{evidence_type}_{YYYY-MM-DD}.{ext}
+```
+
+Examples:
+- `A.5.15_user-access-list_2026-02-28.json`
+- `A.8.8_vulnerability-scan_2026-02-28.csv`
+- `A.8.13_backup-test-results_2026-02-28.pdf`
+
+## Step-by-Step Workflow
+
+### Step 1: Identify Evidence Gaps
+
+Determine what evidence is missing or stale.
+
+```
+# If compliance MCP is available:
+list_evidence_gaps(framework="iso27001_2022", tier="critical")
+
+# If reading local compliance data:
+# Check compliance/evidence/*.md files for upload_status != "OK"
+# Check renewal_next dates for upcoming expirations
+```
+
+### Step 2: Prioritize Collection
+
+Order evidence collection by:
+1. **Missing evidence for Critical-tier controls** — audit blockers
+2. **Stale evidence past renewal date** — auditor will reject
+3. **Evidence for Relevant-tier controls** — expected but not blocking
+4. **Checkbox-tier evidence** — policies and attestations
+
+### Step 3: Collect by Platform
+
+Run evidence collection commands grouped by platform to minimize context-switching.
+
+#### GitHub Evidence
+```bash
+# Org settings: MFA requirement, default permissions
+gh api orgs/{org} | jq '{
+  two_factor_requirement_enabled,
+  default_repository_permission,
+  members_can_create_public_repositories
+}' > evidence/A.5.17_github-org-mfa_$(date +%Y-%m-%d).json
+
+# Branch protection on production repos
+for repo in $(gh repo list {org} --json name -q '.[].name'); do
+  gh api repos/{org}/$repo/branches/main/protection 2>/dev/null | \
+    jq '{repo: "'$repo'", protection: .}' >> evidence/A.8.32_branch-protection_$(date +%Y-%m-%d).json
+done
+
+# Recent merged PRs (change management evidence)
+gh pr list --state merged --limit 50 --json number,title,author,reviewDecision,mergedAt,mergedBy \
+  > evidence/A.8.32_change-records_$(date +%Y-%m-%d).json
+
+# Dependabot alerts (vulnerability management)
+gh api repos/{org}/{repo}/dependabot/alerts?state=open \
+  > evidence/A.8.8_dependabot-alerts_$(date +%Y-%m-%d).json
+
+# Secret scanning alerts
+gh api orgs/{org}/secret-scanning/alerts --paginate \
+  > evidence/A.8.24_secret-scanning_$(date +%Y-%m-%d).json
+
+# Audit log
+gh api orgs/{org}/audit-log?per_page=100 \
+  > evidence/A.8.15_github-audit-log_$(date +%Y-%m-%d).json
+```
+
+#### GCP Evidence
+```bash
+# IAM policy (access control)
+gcloud projects get-iam-policy {project} --format=json \
+  > evidence/A.5.15_gcp-iam-policy_$(date +%Y-%m-%d).json
+
+# Service accounts
+gcloud iam service-accounts list --format=json \
+  > evidence/A.5.16_gcp-service-accounts_$(date +%Y-%m-%d).json
+
+# Audit logging config
+gcloud projects get-iam-policy {project} --format=json | jq '.auditConfigs' \
+  > evidence/A.8.15_gcp-audit-config_$(date +%Y-%m-%d).json
+
+# Log sinks (centralization)
+gcloud logging sinks list --format=json \
+  > evidence/A.8.15_gcp-log-sinks_$(date +%Y-%m-%d).json
+
+# Compute instances (asset inventory)
+gcloud compute instances list --format=json \
+  > evidence/A.5.9_gcp-compute-inventory_$(date +%Y-%m-%d).json
+
+# Cloud SQL backup config
+gcloud sql backups list --instance={instance} --format=json \
+  > evidence/A.8.13_gcp-sql-backups_$(date +%Y-%m-%d).json
+
+# Firewall rules
+gcloud compute firewall-rules list --format=json \
+  > evidence/A.8.20_gcp-firewall-rules_$(date +%Y-%m-%d).json
+```
+
+#### Azure Evidence
+```bash
+# Role assignments (access control)
+az role assignment list --all --output json \
+  > evidence/A.5.15_azure-role-assignments_$(date +%Y-%m-%d).json
+
+# Activity log (audit trail)
+az monitor activity-log list --max-events 100 --output json \
+  > evidence/A.8.15_azure-activity-log_$(date +%Y-%m-%d).json
+
+# Network security groups
+az network nsg list --output json \
+  > evidence/A.8.20_azure-nsgs_$(date +%Y-%m-%d).json
+
+# Backup jobs
+az backup job list --resource-group {rg} --vault-name {vault} --output json \
+  > evidence/A.8.13_azure-backup-jobs_$(date +%Y-%m-%d).json
+
+# Storage encryption
+az storage account list --query "[].{name:name, encryption:encryption}" --output json \
+  > evidence/A.8.24_azure-storage-encryption_$(date +%Y-%m-%d).json
+```
+
+#### Google Workspace Evidence
+```bash
+# User list with MFA status
+gam print users fields primaryEmail,name,isEnrolledIn2Sv,isEnforcedIn2Sv,lastLoginTime,suspended \
+  > evidence/A.5.17_workspace-users-mfa_$(date +%Y-%m-%d).csv
+
+# Admin roles
+gam print admins > evidence/A.8.2_workspace-admins_$(date +%Y-%m-%d).csv
+
+# Mobile devices
+gam print mobile > evidence/A.8.1_workspace-mobile-devices_$(date +%Y-%m-%d).csv
+```
+
+#### macOS Endpoint Evidence
+```bash
+# FileVault encryption
+fdesetup status > evidence/A.8.24_filevault-status_$(date +%Y-%m-%d).txt
+
+# System configuration
+system_profiler SPHardwareDataType SPSoftwareDataType \
+  > evidence/A.8.1_endpoint-config_$(date +%Y-%m-%d).txt
+
+# Screen lock settings
+profiles show -type configuration 2>/dev/null | grep -A10 -i "lock\|idle\|screensaver" \
+  > evidence/A.6.7_screenlock-config_$(date +%Y-%m-%d).txt
+```
+
+### Step 4: Validate Evidence Package
+
+Check completeness before submitting to auditor:
+
+1. **Completeness**: Do you have evidence for every applicable control in the SoA?
+2. **Freshness**: Is every piece of evidence within the required age?
+3. **Format**: Are API exports in JSON/CSV with timestamps? Screenshots have system clock visible?
+4. **Naming**: Files follow the naming convention?
+5. **Coverage**: Critical-tier controls have at least 2 forms of evidence?
+
+```
+# If compliance MCP is available:
+list_evidence_gaps(framework="iso27001_2022")  # Should return empty for complete package
+```
+
+### Step 5: Generate Evidence Index
+
+Create an index file listing all evidence, mapped to controls:
+
+```markdown
+# Evidence Package Index
+Generated: {date}
+Audit period: {start} to {end}
+
+| Control | Evidence File | Type | Collected | Status |
+|---------|--------------|------|-----------|--------|
+| A.5.15 | gcp-iam-policy_2026-02-28.json | API export | 2026-02-28 | Current |
+| A.5.17 | workspace-users-mfa_2026-02-28.csv | API export | 2026-02-28 | Current |
+| ... | ... | ... | ... | ... |
+```
+
+## DO / DON'T
+
+### DO
+- Use API exports with ISO 8601 timestamps over screenshots whenever possible
+- Collect evidence from the SOURCE system (IdP, not a secondary report)
+- Include metadata: collection date, system version, user who collected
+- Store evidence in version-controlled directory with clear naming
+- Collect evidence for the AUDIT PERIOD (usually past 12 months), not just current state
+- Use `screencapture -x ~/evidence/{filename}.png` for screenshots (captures without shadow/border)
+
+### DON'T
+- Take screenshots without visible system clock (menu bar on macOS, taskbar on Windows)
+- Collect evidence from sandbox/staging instead of production
+- Manually edit evidence after collection (auditors may verify against source)
+- Wait until the week before the audit to collect everything
+- Assume stale evidence is acceptable — check freshness requirements above
+- Mix evidence from different audit periods in the same file
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| API command requires auth | Use existing local credentials: `gcloud auth login`, `az login`, `gh auth login` |
+| Tool not installed | Install: `brew install gh`, `brew install --cask google-cloud-sdk`, `brew install azure-cli` |
+| Insufficient permissions | Request read-only access to the relevant service; document the access request as evidence |
+| Evidence too large | Use `--limit` or `--max-events` flags; collect summary statistics instead of full export |
+| Vendor won't provide SOC 2 report | Request via their trust center; if unavailable, document the request and use their security page |
+| Screenshot doesn't include clock | On macOS: use full-screen capture, or `screencapture -x` which includes menu bar |
+
+## Rules
+
+For detailed evidence collection guidance by topic:
+
+| File | Coverage |
+|------|----------|
+| `rules/api-exports.md` | CLI commands by cloud provider (GCP, Azure, AWS, GitHub, Google Workspace) |
+| `rules/screenshot-guide.md` | When and how to take audit-ready screenshots |
+| `rules/evidence-types.md` | Evidence type requirements per control domain |
+
+## Attribution
+
+Evidence collection procedures and control guidance developed with [Internal ISO Audit](https://internalisoaudit.com) (Hazel Castro, ISO 27001 Lead Auditor, 14+ years, 100+ audits).
+
+## Runtime Detection
+
+1. **Compliance MCP server available** (best) — Automated gap detection, evidence freshness tracking
+2. **Local compliance data available** (good) — Reads evidence status from `compliance/evidence/*.md`
+3. **Reference only** (baseline) — Uses embedded checklists and command reference