docs: v1.0.0 docs audit — fix links, stale outputs, and missing options

[Krishan27]

Summary

Full audit of all FlagLint documentation against the v1.0.0 binary. Every CLI command shown in docs was run against the built binary; output was compared to what the docs claim.

Broken internal links fixed

• 5 pages linked to /guides/launchdarkly-to-openfeature-nodejs/ (missing /docs/ prefix) — now corrected in audit.md, migrate.md, validate.md, quickstart.md, and blog/launchdarkly-flag-debt.md
• 23 GitHub "Edit this page" links pointed to the wrong file path (docs-src/content/docs/cli/ instead of docs-src/content/docs/docs/cli/ etc.) — fixed across all CLI, concept, guide, tutorial, reference, and integration pages

Stale CLI output fixed

• audit.md, effort-estimate.md, quickstart.md, docs/index.md, homepage terminal demo: corrected from 53/100 · 10/9 to 50/100 · 10/10 and effort from 20.8h–40h to 22.8h–43.9h (verified against actual binary output)
• migrate.md, quickstart.md, tutorials/migrate-a-node-service.md: corrected from LaunchDarkly usages found: 19 · Manual review: 9 · Skipped: 9 to 20 · 10 · 10

False feature claims removed

• FAQ claimed .flaglintrc.yaml is supported — YAML config is not built; corrected to JSON-only
• json-output.md claimed flaglint scan --write-baseline exists — --write-baseline is only on audit; corrected

v1.0.0 missing features documented

• audit.md options table: added missing --write-baseline <file> option
• validate.md: completely rewritten to document --baseline and --fail-on-new options, add full options table, baseline mode workflow, and per-command exit codes table
• cli/exit-codes.md: updated from pre-v1 vague text to the stable v1.x 0/1/2/3 contract

CI YAML bug fixed

• blog/launchdarkly-openfeature-argument-order-bug.md: removed if: always() from the validate step (it belonged only on SARIF upload steps, not on the policy gate itself)

Test plan

• All changes verified against node dist/bin/flaglint.js output from built v1.0.0 binary
• No TypeScript source files changed
• No package.json changes
• No private/confidential files staged
• Conventional commit format used

Summary by CodeRabbit

• Documentation
  • Enhanced CLI exit codes reference with a stable, machine-readable contract and clearer per-command behavior.
  • Expanded “Baseline Mode” guidance for CI validation using --write-baseline, --baseline, and --fail-on-new.
  • Clarified supported config files (JSON only: .flaglintrc.json or flaglint.config.json) and baseline file provenance.
  • Updated CLI and homepage example outputs (audit, migrate, validate, scan-related flows, effort estimate, quickstart).
  • Corrected multiple documentation navigation/footer links, including guide URLs and GitHub “Edit this page” links.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: c36f0985-55ec-4f11-ac22-6cfff2a09a69

📥 Commits

Reviewing files that changed from the base of the PR and between 20107a4 and 5331c4f.

📒 Files selected for processing (1)

• docs-src/pages/index.astro

✅ Files skipped from review due to trivial changes (1)

• docs-src/pages/index.astro

---

📝 Walkthrough

Walkthrough

Documentation-only update that expands flaglint validate with a new Baseline Mode section, rewrites the exit-code contract table with per-command notes, refreshes CLI output example counts across quickstart/audit/migrate/tutorial pages, corrects guide link paths from /guides/ to /docs/guides/, and normalizes "Edit this page on GitHub" footer links across ~30 pages.

Changes

FlagLint Documentation Updates

Layer / File(s)	Summary
flaglint validate: baseline mode, SARIF, exit codes docs-src/content/docs/docs/cli/validate.md	Front-matter updated; new "Baseline Mode" section documents --baseline and --fail-on-new CI workflow; SARIF section reorganized; Exit Codes table added for codes 0/1/2; Further Reading and Feedback footer refreshed.
Exit code contract and per-command notes docs-src/content/docs/docs/cli/exit-codes.md, docs-src/content/docs/docs/reference/exit-codes.md	"Common Codes" table replaced with "Exit Code Table" adding a "When it occurs" column for codes 0–3 and 130; command-specific notes added for audit, scan, migrate --dry-run, migrate --apply, validate --no-direct-launchdarkly, and validate --baseline --fail-on-new; "See also" link added to Feedback.
CLI output example counts and audit summary wording docs-src/content/docs/docs/cli/audit.md, docs-src/content/docs/docs/cli/effort-estimate.md, docs-src/content/docs/docs/cli/migrate.md, docs-src/content/docs/docs/quickstart.md, docs-src/content/docs/docs/index.md, docs-src/content/docs/docs/tutorials/migrate-a-node-service.md, docs-src/pages/index.astro	Audit summary wording changes from "unique flags across call sites" to "flags — N high risk, N medium risk"; migrate dry-run counts increase (19→20 usages, 9→10 manual review, 9→10 skipped); --effort-estimate range and readiness scores updated throughout; --write-baseline <file> option added to audit options table.
URL path fixes, CI example, FAQ, and baseline source clarification docs-src/content/docs/blog/launchdarkly-flag-debt.md, docs-src/content/docs/blog/launchdarkly-openfeature-argument-order-bug.md, docs-src/content/docs/docs/cli/audit.md, docs-src/content/docs/docs/cli/migrate.md, docs-src/content/docs/docs/quickstart.md, docs-src/content/docs/docs/reference/faq.md, docs-src/content/docs/docs/reference/json-output.md, docs-src/content/docs/docs/reference/limitations.md	Guide links corrected from /guides/ to /docs/guides/; CI blog example changes to npx flaglint@latest and removes if: always(); FAQ removes YAML config support, specifying JSON-only (.flaglintrc.json / flaglint.config.json); json-output.md narrows baseline file writer to flaglint audit --write-baseline only; limitations.md GitHub edit link path corrected.
Bulk "Edit this page on GitHub" link normalization docs-src/content/docs/docs/cli/*, docs-src/content/docs/docs/concepts/*, docs-src/content/docs/docs/guides/*, docs-src/content/docs/docs/integrations/*, docs-src/content/docs/docs/tutorials/*, docs-src/content/docs/docs/reference/*, docs-src/content/docs/docs/trust/*, docs-src/content/docs/docs/*	Single-line "Edit this page on GitHub" footer link added or corrected across ~24 pages in CLI, concepts, guides, integrations, tutorials, reference, trust, and top-level docs sections.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related issues

• docs/cli: formalize stable exit-code contract for v1.x #168: This PR directly implements the stable exit-code contract documentation requested in that issue, including the expanded exit-code table with "When it occurs" column and per-command exit behavior notes.
• docs/cli: formalize stable exit-code contract for v1.x #154: This PR fulfills the exit-code formalization requirement by updating exit-codes.md with explicit meanings for codes 0, 1, 2, 3, and 130 across FlagLint v1.x.

Possibly related PRs

• flaglint/flaglint#162: This PR updates the same blog and docs pages that link to the LaunchDarkly→OpenFeature guide, correcting the path from /guides/ to /docs/guides/ introduced by that PR.
• flaglint/flaglint#176: This PR documents the same baseline mode workflow (--baseline, --fail-on-new, --write-baseline, exit codes) that the retrieved ADR defines.
• flaglint/flaglint#182: This PR updates the same exit-codes and validate documentation to reflect the v1.x stable exit-code contract covered by that PR.

Poem

🐇 Hippity-hop through the docs we go,
Fixing the links from /guides to /docs/guides, just so!
The baseline is written, the exit codes gleam,
"Edit this page" now shines on every team.
The rabbit has tidied each footnote with care —
Clean docs for all, from here to there! 🌿

🚥 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 directly describes the main changes: comprehensive documentation audit fixing broken links, outdated outputs, and missing v1.0.0 options/features.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/v1-docs-audit-fixes

---

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

[cloudflare-workers-and-pages]

Deploying flaglint with    Cloudflare Pages

Latest commit:	5331c4f
Status:	✅  Deploy successful!
Preview URL:	https://7c90b449.flaglint.pages.dev
Branch Preview URL:	https://docs-v1-docs-audit-fixes.flaglint.pages.dev

View logs

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

docs-src/content/docs/blog/launchdarkly-openfeature-argument-order-bug.md (1)

143-143: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Pin the CLI version in the CI example.

@latest makes the workflow drift over time and can change behavior without a docs update. Pin the version you validated, or note explicitly that this example intentionally floats on the latest release.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs-src/content/docs/blog/launchdarkly-openfeature-argument-order-bug.md` at
line 143, The npx command in the CI example uses `@latest` for the flaglint
package version, which can cause unpredictable behavior changes over time.
Either replace `@latest` with a specific pinned version number that you have
validated (e.g., `@1.2.3`), or add an explicit note in the documentation
explaining that this example intentionally floats on the latest release and the
reasons for doing so.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs-src/content/docs/docs/cli/exit-codes.md`:
- Around line 15-16: The exit code 1 row currently mixes failure modes from both
validate and migrate commands, including the --allow-dirty flag which only
applies to migrate. Remove the dirty working tree condition (the part mentioning
--allow-dirty) from the exit code 1 row for validate, keeping only the
validate-specific failures like policy validation and --fail-on-new findings.
Then add the dirty working tree condition to the appropriate exit code row that
documents migrate command failures.

In `@docs-src/pages/index.astro`:
- Around line 915-918: Update the terminal demo output in the index.astro file
to match the actual CLI output terminology. Change the shortened labels
"Readiness:" to match the CLI output's "Migration readiness:" label, and ensure
the effort estimate labels are consistent with what the actual audit command
outputs. Apply this correction to both instances mentioned (around lines 915-918
and line 928) so the homepage demo accurately reflects the real binary output.

---

Nitpick comments:
In `@docs-src/content/docs/blog/launchdarkly-openfeature-argument-order-bug.md`:
- Line 143: The npx command in the CI example uses `@latest` for the flaglint
package version, which can cause unpredictable behavior changes over time.
Either replace `@latest` with a specific pinned version number that you have
validated (e.g., `@1.2.3`), or add an explicit note in the documentation
explaining that this example intentionally floats on the latest release and the
reasons for doing so.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 4f7e6503-379a-49d6-8c91-bab543ab8044

📥 Commits

Reviewing files that changed from the base of the PR and between 951ceb2 and 20107a4.

📒 Files selected for processing (37)

• docs-src/content/docs/blog/launchdarkly-flag-debt.md
• docs-src/content/docs/blog/launchdarkly-openfeature-argument-order-bug.md
• docs-src/content/docs/docs/cli/audit.md
• docs-src/content/docs/docs/cli/configuration.md
• docs-src/content/docs/docs/cli/effort-estimate.md
• docs-src/content/docs/docs/cli/exit-codes.md
• docs-src/content/docs/docs/cli/migrate.md
• docs-src/content/docs/docs/cli/report-formats.md
• docs-src/content/docs/docs/cli/scan.md
• docs-src/content/docs/docs/cli/validate.md
• docs-src/content/docs/docs/concepts/how-flaglint-works.md
• docs-src/content/docs/docs/concepts/openfeature-boundary.md
• docs-src/content/docs/docs/concepts/source-level-debt-signals.md
• docs-src/content/docs/docs/enterprise-demo.md
• docs-src/content/docs/docs/guides/express.md
• docs-src/content/docs/docs/guides/manual-review-patterns.md
• docs-src/content/docs/docs/guides/monorepos.md
• docs-src/content/docs/docs/guides/nestjs.md
• docs-src/content/docs/docs/guides/troubleshooting.md
• docs-src/content/docs/docs/index.md
• docs-src/content/docs/docs/integrations/github-actions.md
• docs-src/content/docs/docs/integrations/openfeature-provider.md
• docs-src/content/docs/docs/integrations/opentelemetry.md
• docs-src/content/docs/docs/quickstart.md
• docs-src/content/docs/docs/reference/changelog.md
• docs-src/content/docs/docs/reference/exit-codes.md
• docs-src/content/docs/docs/reference/faq.md
• docs-src/content/docs/docs/reference/json-output.md
• docs-src/content/docs/docs/reference/limitations.md
• docs-src/content/docs/docs/reference/supported-scope.md
• docs-src/content/docs/docs/trust/security.md
• docs-src/content/docs/docs/tutorials/add-openfeature-provider.md
• docs-src/content/docs/docs/tutorials/enforce-in-github-actions.md
• docs-src/content/docs/docs/tutorials/migrate-a-node-service.md
• docs-src/content/docs/docs/tutorials/shared-client-architecture.md
• docs-src/content/docs/docs/why-flaglint.md
• docs-src/pages/index.astro