docs: align repository documentation with MVP status#88
Merged
Conversation
Documentation-only audit. No code, evaluator, or rule changes; no new features; no Cloudflare work; no changes to PR #37 or #78. User-facing copy fixed: - README.md: replace misleading ASCII diagram (3 rewrites / Tailored CV) with the actual MVP outputs (Score, Issues, Strengths, ATS verdict, Archetype); clarify that /evaluate-cv ./my-resume.pdf works only because Claude Code reads PDFs natively (the local CLI/web UI parse .md and .txt only). - apps/web-ui layout.tsx: Next.js metadata description replaced with honest CV-evaluator copy (no longer 'Build a tailored resume...'). - apps/web-ui/README.md: list all three routes (/, /results, /feedback), note the static-export + privacy-first posture. - apps/cli/README.md: same PDF-clarification note as the root README. - package.json descriptions (root + core + cli): remove 'tailor / build' wording; describe the deterministic evaluator. - packages/intelligence/README.md: list the eight shipped roles (matches README and the actual implementation) and correct the default archetype (Backend Engineer, not Software Engineer). - packages/eval/README.md: drop the outdated LLM-provider claim; the MVP is fully deterministic. - .claude/skills/cv-evaluation/SKILL.md: 'local MVP', not 'hosted product'; default archetype corrected. - ROADMAP.md: status note added; Phase-1 / #74 / #75 / #76 / #85 / #87 marked as recently shipped; only #37 and #78 remain in progress. Historical docs marked with status notes (not rewritten, just flagged as pre-release context): ARCHITECTURE.md, PROPOSAL.md, PHASE-1.md, V1_SCOPE.md, MVP_DEMO_PLAN.md, PR_CLEANUP_HANDOFF.md, POST_MERGE_VALIDATION.md, REMAINING_PRS_PLAN.md, PR85_ROLLBACK_PLAN.md. Each now points readers to docs/MVP_RELEASE_STATUS.md. New: - docs/REPO_DOCS_AUDIT.md records the audit date, files reviewed, files changed, outdated claims found and fixed, historical docs left intentionally unchanged, remaining risks, and the validation results. Validates: pnpm test (12/12), pnpm lint (0 errors), pnpm build (6/6, fresh --force: emits /, /_not-found, /feedback, /results).
📝 WalkthroughWalkthroughThis PR is a documentation and metadata refresh aligning READMEs, package descriptions, and app metadata with the shipped local MVP CV evaluator, adds historical status notes to legacy planning docs, introduces a new repo docs audit file, and switches the archetype fallback from "Software Engineer" to "Backend Engineer." ChangesMVP documentation and metadata refresh
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related issues
Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 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 `@packages/intelligence/README.md`:
- Around line 9-18: The archetype inventory in the README does not match the
runtime registry used by `detectArchetype()` and `src/archetypes/index.ts`.
Update the documentation to reflect the actual registered archetypes and the
real fallback from `softwareEngineer` (“Software Engineer”), or expand the
registry/tests so the eight listed roles and Backend Engineer fallback are truly
supported. Keep `detectArchetype`, `index.ts`, and any archetype registration
tests in sync.
In `@README.md`:
- Around line 29-32: The README diagram is hard-coding the issue count as 5 even
though evaluate() returns a variable-length issues array and the docs only
guarantee at least 3 issues. Update the README content near the
Engine/evaluate() description to use a non-fixed count or phrasing that reflects
variable output, and keep the wording aligned with the evaluate() API and the
documented scoring dimensions.
🪄 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: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 4b574466-5366-433b-b6ab-dfa44d379108
📒 Files selected for processing (21)
.claude/skills/cv-evaluation/SKILL.mdREADME.mdROADMAP.mdapps/cli/README.mdapps/web-ui/README.mdapps/web-ui/src/app/layout.tsxdocs/ARCHITECTURE.mddocs/MVP_DEMO_PLAN.mddocs/PHASE-1.mddocs/POST_MERGE_VALIDATION.mddocs/PR85_ROLLBACK_PLAN.mddocs/PROPOSAL.mddocs/PR_CLEANUP_HANDOFF.mddocs/REMAINING_PRS_PLAN.mddocs/REPO_DOCS_AUDIT.mddocs/V1_SCOPE.mdpackage.jsonpackages/cli/package.jsonpackages/core/package.jsonpackages/eval/README.mdpackages/intelligence/README.md
docs/MVP_DEMO_PLAN.md still said 'Node 22+' in the prereqs section, which conflicts with the actual repo metadata (Node >= 20.0.0 in package.json) and with the authoritative setup guide in docs/LOCAL_DEMO.md. Replace the prereqs with a short pointer to LOCAL_DEMO.md plus a one-line accurate summary, so this historical demo-readiness doc no longer contradicts current setup instructions. docs/REPO_DOCS_AUDIT.md: remove the corresponding entry from the 'remaining documentation risks' list, fix the resulting item numbering, and add a note recording that the Node-version item was resolved before merge. No code, evaluator, or rule changes. No new features. PR #37 and PR #78 untouched. Validates: pnpm test 12/12, pnpm lint 0 errors, pnpm build 6/6 (fresh --force, emits /, /_not-found, /feedback, /results).
Deploying with
|
| Status | Name | Latest Commit | Updated (UTC) |
|---|---|---|---|
| ❌ Deployment failed View logs |
cv-builder-web | 9c865b7 | Jul 02 2026, 08:02 PM |
Two unresolved CodeRabbit comments fixed in this commit: 1. README.md — replace hard-coded '5 issues' in the evaluator diagram with the non-fixed wording 'Issues'. evaluate() returns a variable-length issues array; a fixed count would drift as scoring changes. The other diagram labels (Score, Strengths, ATS verdict, Archetype) are kept as-is because they describe deterministic outputs that do not vary in count. 2. packages/intelligence/README.md — the previous audit pass claimed this package ships eight roles and falls back to Backend Engineer. But packages/intelligence/src/archetypes/index.ts registers only three archetypes (Software Engineer, Product Manager, Data & ML Engineer) and DEFAULT_ARCHETYPE is softwareEngineer. Update the README to reflect the actual registry. Add a note clarifying that @cv-builder/core has a separate, broader legacy/runtime registry (7 roles) used by the CLI and Web UI, and that unifying the two registries is a follow-up — see docs/ARCHETYPE_GAP_AUDIT.md. docs/REPO_DOCS_AUDIT.md updated to record that the packages/intelligence/README.md archetype-inventory row was corrected in two steps (the audit pass incorrectly bumped the package claim to 8; this commit brings it back to 3 and adds the @cv-builder/core note). No code changes. No new features. PR #37 and PR #78 untouched. Docs only. Validates: pnpm test 12/12, pnpm lint 0 errors, pnpm build 6/6.
Contributor
Author
|
Both CodeRabbit comments fixed in 9c865b7:
docs/REPO_DOCS_AUDIT.md updated to record the two-step correction on the intelligence README row. No code changes. No new features. PR #37 and PR #78 untouched. Docs only. Validates: pnpm test 12/12, pnpm lint 0 errors, pnpm build 6/6. Ready to merge. |
SaharPak
changed the title
SaharPak
pushed a commit
that referenced
this pull request
Jul 2, 2026
The audit draft was written before the GitHub API assigned the actual issue numbers. It referenced 'issue #97' in three places for the plain-Product-Manager follow-up. The real issue number is #90 (verified via gh issue view). - Line 135: 'issue #97, see footer' -> 'issue #90, see footer' - Line 194: 'Filed as issue #97' -> 'Filed as issue #90' - Line 204: 'follow-up to #97' -> 'follow-up to #90' Also caught by this rebase onto latest main (docs: align repository documentation with MVP status, PR #88). The rebase was conflict-free because PR #88 and the audit modified orthogonal sections of the shared files (README.md, docs/MVP_RELEASE_STATUS.md, and docs/PR_CLEANUP_HANDOFF.md). The rebase confirmed that all five audit findings survived intact: - core registry has 7 live archetypes - intelligence registry has 3 archetypes - plain Product Manager is missing from core - #90 tracks plain Product Manager - #91 tracks registry consolidation No code changes. Docs only. PR #37 and PR #78 untouched. Validates: pnpm test 12/12, pnpm lint 0 errors, pnpm build 6/6.
SaharPak
added a commit
that referenced
this pull request
Jul 2, 2026
* docs: audit role archetype coverage
Adds a comprehensive audit of the role-archetype registries, plus the
small docs-only corrections called out in the audit.
Audited:
- packages/core/src/archetypes/index.ts (7 archetypes, RoleArchetype)
- packages/intelligence/src/archetypes/ (3 archetypes, Archetype)
- packages/schemas/src/archetype.ts (Zod Archetype schema)
- packages/core/src/evaluator/index.ts (live evaluator)
- packages/cli/src/cli.ts (CLI archetypes list)
- apps/web-ui/src/app/{results,components}/* (web UI consumer)
- packages/eval/src/__tests__/fixtures.test.ts (eval fixtures)
- issues, scripts/create-issues.sh, docs/ISSUES_SEED.md, ROADMAP
equivalents in README/docs, V1_SCOPE, PHASE-1, ARCHITECTURE
Key findings:
1. Two parallel archetype registries (core vs intelligence) on
divergent schemas. CLI + Web UI use core (7); prompts + eval
fixtures use intelligence (3).
2. README claimed 8 archetypes; core has 7, intelligence has 3.
Fixed to 7 in README, MVP_RELEASE_STATUS, PR_CLEANUP_HANDOFF.
3. Plain Product Manager detection is broken in the live system:
core has only ai-product-manager, so a non-AI PM CV falls back
to backend-engineer.
Files changed:
- docs/ARCHETYPE_GAP_AUDIT.md (new, 200+ lines)
- README.md: '8 role archetypes' -> '7', removed Machine Learning
Engineer from 'currently built-in' list (not in core), added
pointer to the audit
- docs/MVP_RELEASE_STATUS.md: 8 archetypes -> 7 in two places
- docs/PR_CLEANUP_HANDOFF.md: clarified 3 archetypes in intelligence
vs 7 in core
* docs: fix stale issue numbers in archetype gap audit
The audit draft was written before the GitHub API assigned the actual
issue numbers. It referenced 'issue #97' in three places for the
plain-Product-Manager follow-up. The real issue number is #90
(verified via gh issue view).
- Line 135: 'issue #97, see footer' -> 'issue #90, see footer'
- Line 194: 'Filed as issue #97' -> 'Filed as issue #90'
- Line 204: 'follow-up to #97' -> 'follow-up to #90'
Also caught by this rebase onto latest main (docs: align repository
documentation with MVP status, PR #88). The rebase was conflict-free
because PR #88 and the audit modified orthogonal sections of the
shared files (README.md, docs/MVP_RELEASE_STATUS.md, and
docs/PR_CLEANUP_HANDOFF.md).
The rebase confirmed that all five audit findings survived intact:
- core registry has 7 live archetypes
- intelligence registry has 3 archetypes
- plain Product Manager is missing from core
- #90 tracks plain Product Manager
- #91 tracks registry consolidation
No code changes. Docs only. PR #37 and PR #78 untouched.
Validates: pnpm test 12/12, pnpm lint 0 errors, pnpm build 6/6.
---------
Co-authored-by: Cleanup Bot <cleanup-bot@example.com>
SaharPak
pushed a commit
that referenced
this pull request
Jul 2, 2026
- Update snapshot commit hash: 4e43a3c -> 4b4bb03 (post-#88 + #92) - Total merged PRs: 26 -> 28 (#88 and #92 both merged by SaharPak) - Distinct merged-PR authors: 10 (unchanged) - SaharPak merged-PR count: 6 -> 8 - Open PRs: remove #88 (now merged), add #89 (this PR) - Notable contribution areas: add 'Docs consistency audit' and 'Archetype gap audit' - Privacy: drop private-email field from anonymous-contributor refresh recipe - Last refreshed footer: note PR #88 and PR #92 - Maintainers + Docs sections: credit PR #92 archetype gap audit - Archetype count: 8 -> 7 in IKetutWidiyane and Mohammadreza-Sarvari sections
SaharPak
added a commit
that referenced
this pull request
Jul 2, 2026
* docs: add contributor recognition * docs: tighten contributor recognition accuracy and privacy - Fix distinct merged-PR author count: 9 -> 10 (verified via gh pr list) - Add Cleanup Bot to the Anonymous commits on main table (22 commits) - Add explicit caveat: counts do not capture review, discussion, product thinking, or community support - Remove private email a.hakimi@mohaymen.ir from caveat 4 - Remove fabricated github.com/a.hakimi link (returns 404) - Soften 'not a real contributor' to 'not a human contributor' - Rename 'Top contributors by merged-PR count' to 'Contributors by merged-PR count' to reduce ranking feel * docs: refresh contributor recognition after PR #88 and #92 - Update snapshot commit hash: 4e43a3c -> 4b4bb03 (post-#88 + #92) - Total merged PRs: 26 -> 28 (#88 and #92 both merged by SaharPak) - Distinct merged-PR authors: 10 (unchanged) - SaharPak merged-PR count: 6 -> 8 - Open PRs: remove #88 (now merged), add #89 (this PR) - Notable contribution areas: add 'Docs consistency audit' and 'Archetype gap audit' - Privacy: drop private-email field from anonymous-contributor refresh recipe - Last refreshed footer: note PR #88 and PR #92 - Maintainers + Docs sections: credit PR #92 archetype gap audit - Archetype count: 8 -> 7 in IKetutWidiyane and Mohammadreza-Sarvari sections * docs: fix contributor formatting command --------- Co-authored-by: Cleanup Bot <cleanup-bot@example.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documentation-only audit. Brings every user-facing doc, README copy, package description, and the Claude Code skill in line with what the MVP actually does today (post-PR #87).
No code, evaluator, or rule changes. No new features. No Cloudflare work. PR #37 and PR #78 were not touched.
What changed
User-facing copy fixed
README.md— replaced the misleading ASCII diagram ("3 rewrites / Keywords gap / Tailored CV") with the actual MVP outputs (Score, Issues, Strengths, ATS verdict, Archetype). Clarified the Power-User section:/evaluate-cv ./my-resume.pdfworks only because Claude Code reads PDFs natively; the local web UI and CLI parse.mdand.txtonly.apps/web-ui/src/app/layout.tsx— Next.js metadata description no longer says "Build a tailored resume…"; describes the privacy-first evaluator instead.apps/web-ui/README.md— lists all three routes (/,/results,/feedback), calls out the static-export + privacy posture.apps/cli/README.md— same PDF clarification as the root README.package.jsondescription — "CV builder… tailored resume" → "privacy-first CV evaluator".packages/core/package.jsonandpackages/cli/package.jsondescriptions — "tailor" wording removed; describes the deterministic evaluator.packages/eval/README.md— drops the "LLM-produced EvalResult" claim; the MVP is fully deterministic..claude/skills/cv-evaluation/SKILL.md— "local MVP" instead of "hosted product"; default archetype fixed.ROADMAP.md— status note added; Phase-1 / Rule/flag outdated technologies #74 / chore: expand CodeRabbit config with per-package review guidance #75 / Add CV and JD input screen with file upload and client-side evaluation #76 / Integrate CV Builder MVP foundation and close PR cleanup pass #85 / Prepare CV Builder MVP for community testing #87 marked as recently shipped; only feat(cli): add color output for scores, dimensions, and issues #37 and ci(web-ui): Cloudflare Pages preview deploys + setup docs #78 remain.Historical docs marked with status notes
These describe pre-MVP architecture or pre-merge state. Rather than rewriting them out of context, each one gets a status note at the top pointing readers to
docs/MVP_RELEASE_STATUS.md:docs/ARCHITECTURE.md— describes TanStack Query, Tolgee, Fastify, Telegram,packages/llm/ingestion/templates, none of which exist in the MVPdocs/PROPOSAL.md— same aspirational architecturedocs/PHASE-1.md— pre-PR Prepare CV Builder MVP for community testing #87 Phase-1 plandocs/V1_SCOPE.md— same aspirational scopedocs/MVP_DEMO_PLAN.md— pre-PR Prepare CV Builder MVP for community testing #87 demo-readiness auditdocs/PR_CLEANUP_HANDOFF.md— post-PR Integrate CV Builder MVP foundation and close PR cleanup pass #85 cleanup reportdocs/POST_MERGE_VALIDATION.md— post-PR Integrate CV Builder MVP foundation and close PR cleanup pass #85 validation reportdocs/REMAINING_PRS_PLAN.md— plan for feat(cli): add color output for scores, dimensions, and issues #37 / ci(web-ui): Cloudflare Pages preview deploys + setup docs #78docs/PR85_ROLLBACK_PLAN.md— pre-PR Integrate CV Builder MVP foundation and close PR cleanup pass #85 rollback planNew
docs/REPO_DOCS_AUDIT.md— the audit record (date, files reviewed, files changed, claims fixed, historical docs left intentionally unchanged, remaining risks, validation results).What was intentionally not changed
packages/cli/package.jsondescriptionfield (which is onmain, not on the PR's branch) was updated.apps/web-ui/README.mdroutes section now correctly lists/,/results,/feedbackas static-export routes — it previously listed no routes at all..github/ISSUE_TEMPLATE/*.md,.github/PULL_REQUEST_TEMPLATE.md) were reviewed; no edits needed — they describe the contribution flow, not product claims.Validation results
Run on
docs/repo-consistency-auditat audit time:pnpm testpnpm lintbiome.jsonlinter.recommendeddeprecation notice (unrelated to this audit)pnpm buildpnpm turbo build --force) emits/,/_not-found,/feedback,/resultsas staticPR #37 and #78 confirmation
Audit record
Full audit:
docs/REPO_DOCS_AUDIT.mdSummary by CodeRabbit
New Features
Bug Fixes
Documentation