chore(repo): stop blanket-ignoring docs/, ignore only docs/generated/

[cristim]

Problem

Closes #1169 (review finding HYG-03, P2).

.gitignore blanket-ignored the entire docs/ directory (# Generated docs (security runbooks etc.) / docs/), while docs/ contains tracked, hand-written documentation (DEPLOYMENT.md, DEVELOPMENT.md, smoke-test-multi-account.sh) and the repo's contributor guidance tells people to put documentation there. Any new file under docs/ was silently excluded from git add / git status; the predicted drift had already happened, with ~200KB of review documentation accumulating untracked and invisible to git under docs/code-review/.

Fix

• Narrow the ignore from docs/ to docs/generated/, the generated-runbook output the blanket rule was meant to cover, and document the intent in the comment. Hand-written docs under docs/ are now tracked normally.
• Link docs/DEVELOPMENT.md from the README ## Development section so the guide is discoverable. (docs/DEPLOYMENT.md was already linked from the deployment section, so only the development guide link was missing.)

Test evidence

Verified with git check-ignore -v in a clean worktree of origin/main:

Pre-fix (bug reproduced - every new docs file is trapped):

$ git check-ignore -v docs/new-doc.md docs/generated/runbook.md
.gitignore:137:docs/	docs/new-doc.md
.gitignore:137:docs/	docs/generated/runbook.md

Post-fix:

$ git check-ignore -v docs/new-doc.md        # exit 1, not ignored
$ git check-ignore -v docs/generated/runbook.md
.gitignore:139:docs/generated/	docs/generated/runbook.md
$ git ls-files docs/                          # tracked files unaffected
docs/DEPLOYMENT.md
docs/DEVELOPMENT.md
docs/smoke-test-multi-account.sh

No code changes, so no Go/frontend tests apply; an automated regression test is not idiomatic for .gitignore semantics, the git check-ignore pre/post evidence above replicates the exact failing scenario.

Summary by CodeRabbit

• Documentation

  • Updated the README’s Development section to link to a dedicated development guide covering the local Docker environment, database migrations, hot reload, and debugging workflows.

• Chores

  • Adjusted .gitignore to stop ignoring the entire docs/ directory and instead ignore only generated content under docs/generated/, while keeping hand-written documentation in docs/ tracked.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 5532e788-6742-4670-b360-0de557b188b6

📥 Commits

Reviewing files that changed from the base of the PR and between 43ceec2 and 7db2b36.

📒 Files selected for processing (2)

• .gitignore
• README.md

🚧 Files skipped from review as they are similar to previous changes (2)

• README.md
• .gitignore

---

📝 Walkthrough

Walkthrough

Updated .gitignore to ignore only generated documentation under docs/generated/ and added a README link to docs/DEVELOPMENT.md, covering Docker setup, migrations, hot reload, and debugging workflows.

Changes

Documentation Discovery and Tracking

Layer / File(s)	Summary
Fix gitignore and link development guide .gitignore, README.md	.gitignore now ignores only docs/generated/, while the README Development section links to docs/DEVELOPMENT.md and its documented workflows.

Estimated code review effort: 2 (Simple) | ~8 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and accurately summarizes the main change to .gitignore and docs handling.
Linked Issues check	✅ Passed	The PR replaces the blanket docs/ ignore with docs/generated/ and links the development docs as requested in #1169.
Out of Scope Changes check	✅ Passed	The diff stays focused on .gitignore and README updates, with no unrelated code or test changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/hyg-03-docs-gitignore

---

_{Comment @coderabbitai help to get the list of available commands.}

[cristim]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[cristim]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[cristim]

Adversarial review -- PR #1211

Reviewed against the stated risk surfaces (un-ignore exposure, docs/generated/ aim, generator output paths, machine-specific paths in tracked docs, CI implications, base branch). Net: no blocking findings. One out-of-scope follow-up filed.

What I checked

• The actual diff is the claimed diff. git diff $(git merge-base origin/main HEAD)..HEAD --name-only returns exactly .gitignore and README.md (8 +, 2 -). No drive-by edits, no accidentally-included files from the now-un-ignored docs/ tree.
• Pre/post git check-ignore reproduces the PR description verbatim.

  pre  (origin/main .gitignore):
    .gitignore:139:docs/    docs/new-doc.md
    .gitignore:139:docs/    docs/generated/runbook.md
  post (HEAD .gitignore):
    docs/new-doc.md         -> exit 1 (not ignored)
    .gitignore:141:docs/generated/   docs/generated/runbook.md
  

  Existing tracked files (docs/DEPLOYMENT.md, docs/DEVELOPMENT.md, docs/smoke-test-multi-account.sh) are not matched by either pattern -- already tracked before/after, no behaviour change for them.
• No surprises slip into the tracked tree. git ls-tree -r HEAD -- docs/ returns exactly the three pre-existing files. The "~200KB review docs" the issue mentions live only in the verifier's local working tree; this PR neither commits nor exposes them on the remote.
• docs/generated/ is prospective, not retrospective. Grepped *.go, *.sh, *.yml, *.yaml, Makefile, *.mk, *.toml, *.json, *.ts, *.tsx, *.py for docs/generated, runbook, security-audit, security-runbook -- zero references. There is no current generator pointed at docs/generated/; the rule is preventive for the planned-but-not-yet-wired runbook generator the original blanket-ignore comment referred to. If/when a generator is wired up and emits to a different subdir (docs/runbooks/, docs/security/), the ignore pattern will need a matching update -- but that's a future concern, not a current bug.
• No machine-specific absolute paths in the tracked docs. grep -nE "/Users/|/home/[a-z]+|Dropbox|cristi" docs/ returns nothing across all three files -- memory feedback_no_absolute_paths_in_code.md clean.
• No CI build pipeline change needed. Docs are markdown + a shell script; nothing to rebuild on push.
• Memory feedback_pr_workflow.md: base is main ✓.
• CR pre-merge checks. All 5 pre-merge checks pass (Description, Title, Linked Issues, Out of Scope Changes, Docstring Coverage). No CR-actionable findings on the diff.
• The docs/ blanket ignore actually was the bug. CLAUDE.md:24 says "Use /docs for documentation and markdown files" -- contributors and agents are told to put docs there, but .gitignore:137 docs/ was silently dropping every new addition from git add. The verifier verdict in HYG-03: docs/ blanket-gitignored while containing tracked documentation; new docs silently ignored #1169 is confirmed: bug reproduced pre-fix, gone post-fix.

CI state

All four failing checks (Lint Code, Security Scanning, Integration Tests, E2E Tests, CI Success cascade) are repo-wide pre-existing failures unrelated to this PR's 2-file diff:

• Lint Code -- 2875 issues across the repo (errcheck 107, gocritic 446, godot 1188, gosec 43, govet 360, misspell 604, etc.). None in .gitignore or README.md.
• Security Scanning -- govulncheck HIGH/CRITICAL in pinned dependencies (uses golang.org/x/vuln/cmd/govulncheck@v1.1.4, correctly pinned per memory feedback_ci_tool_version_pin.md).
• Integration Tests + E2E Tests -- duplicate migration file: 000074_repair_partial_migration_058_067.down.sql -- the exact failure documented in memory project_migration_number_collisions.md (only fails in CI on the merge ref, not local pre-commit). Already addressed at the repo level in commits 5894580f3 (renumber audit_actor_stamps 074->077) and 451a70f73 (merge of PR fix(db): renumber audit_actor_stamps migration to clear 000074 collision #1261); a rebase onto current main will resolve. Branch is currently 1 ahead / 5 behind origin/main.

None introduced by this PR. From a code-correctness standpoint the diff is mergeable; the UNSTABLE state reflects unmerged migration-collision and repo-level debt that a fresh rebase + the already-merged #1261 will clear.

Out-of-scope follow-up filed

• #1329 -- providers/azure/internal/recommendations/converter.go:50 references docs/code-review/09-provider-azure.md, which git ls-files docs/code-review/ shows was never committed (it lived only in the verifier's local working tree and the blanket docs/ ignore prevented staging). Pre-existing dangling pointer that this PR makes visible: now that docs/ is no longer blanket-ignored, readers chasing the cited M1/M2 finding land on a 404. Fix is either commit the missing doc or drop the trailing sentence from the comment. type/chore, priority/p3, severity/low, urgency/eventually, impact/internal, effort/xs, triaged.

Verdict

No fix needed on PR #1211 itself. The core claim (blanket docs/ ignore swapped for narrow docs/generated/; hand-written docs surface; tracked files unaffected) is fully verified end-to-end with git check-ignore reproduction matching the PR description verbatim. CR pre-merge checks all green. Rebase onto current main once #1261 is in to clear the migration-collision noise, then merge.

[cristim]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[cristim]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[cristim]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[cristim]

Merge-prep bot: rebased onto main (73166c2). No Go or frontend files touched. gitignore pattern verified: docs/generated/runbook.md is ignored (exit 0), docs/DEVELOPMENT.md is not ignored (exit 1). No build/test gates required for .gitignore + README.md only change.

[cristim]

Merge-prep bot: rebased onto current main (e8da1c4) to resolve the .gitignore conflict introduced when #1090 (docs CLI reference) also edited .gitignore.

Conflict resolution by intent, keeping BOTH deliverables:

• docs(cli): add structured CLI reference for undocumented flags (filters, purchase-safety, cloud-setup) #1090 wanted docs/cli/ tracked (it added a blanket docs/* + !docs/cli).
• chore(repo): stop blanket-ignoring docs/, ignore only docs/generated/ #1211 wants only docs/generated/ ignored so hand-written docs (docs/DEVELOPMENT.md, docs/DEPLOYMENT.md) stay tracked; the blanket docs/* is exactly the regression chore(repo): stop blanket-ignoring docs/, ignore only docs/generated/ #1211 removes.

Merged to the narrow docs/generated/ rule, which satisfies both: generated output is ignored, and docs/cli/ + hand-written docs are all tracked. The comment now explicitly warns against re-adding a blanket docs/* and notes docs/cli/ is tracked.

Verification (git check-ignore against the rebased tree):

• docs/generated/somefile -> IGNORED (matches .gitignore:143 docs/generated/)
• docs/DEVELOPMENT.md -> NOT ignored
• docs/cli/README.md -> NOT ignored
• Swept all currently-tracked docs/ files: none got newly ignored; all four docs(cli): add structured CLI reference for undocumented flags (filters, purchase-safety, cloud-setup) #1090 docs/cli/*.md files remain tracked.

Diff intact: .gitignore + README.md (+10/-4). Pushed to fix/hyg-03-docs-gitignore.

[cristim]

Merged to main (rebased, CLEAN + all CI green; closes #1169). Narrows the docs ignore to docs/generated/ so generated output stays ignored while hand-written docs + docs/cli/ (from #1090) stay tracked.