RFC: End-User Setup Wizard for Local Onboarding

[syahmiharith]

RFC: End-User Setup Wizard for Local Onboarding

References

• Discussion The Vision: Free AI-Powered Job Search for Everyone #156 — The Vision: Free AI-Powered Job Search for Everyone

1. Problem

Career-Ops is powerful, but the first-time setup still assumes users are comfortable creating and editing several local Markdown/YAML files manually.

Today, a new user may need to prepare or configure:

• cv.md
• config/profile.yml
• modes/_profile.md
• portals.yml
• data/applications.md
• data/pipeline.md
• output directories such as reports/, output/, and jds/

This is manageable for technical users, but it creates friction for average job seekers.

The project vision in #156 explicitly points toward a simpler setup wizard: paste a CV, pick target roles, and get started. This RFC proposes a local, terminal-based onboarding wizard that supports that direction without changing Career-Ops into a SaaS, web app, or desktop app.

The goal is to make the existing local-first workflow easier to initialize.

2. Proposed Solution

Add a local setup wizard exposed through:

npm run setup

Internally, this would run:

node setup.mjs

The wizard should help users create missing user-layer files through guided prompts.

The first screen should offer:

Career-Ops Setup Wizard

Choose setup mode:

1. Quick setup with existing CV
2. Guided setup without existing CV
3. Resume existing setup
4. Exit

The wizard should support three implementation slices:

1. Quick setup with existing CV
2. Guided setup for users without a ready CV
3. Advanced fine-tuning and resume-existing-setup support

The first PR should only implement the smallest useful slice unless maintainers prefer a different breakdown.

3. Goals

• Add a local npm run setup wizard.
• Keep onboarding local-first and terminal-based.
• Create missing user-layer files from guided prompts.
• Keep the default path simple: CV + target roles + location preference.
• Offer optional advanced fine-tuning for users who want more control.
• Never overwrite existing user files without explicit file-level confirmation.
• Reuse npm run doctor for validation instead of duplicating validation logic.
• Keep user-specific personalization out of system-layer files.

4. Non-Goals

This RFC does not propose:

• A SaaS product
• A web onboarding UI
• A desktop app
• Database-backed onboarding
• Multi-user profiles
• PDF/DOCX parsing in the first implementation
• AI-assisted CV parsing in the first implementation
• Browser upload flow
• LinkedIn scraping or authenticated job-board automation
• Changes to shared mode files
• Replacing npm run doctor
• Changing evaluation scoring logic
• Changing report generation logic

5. User Flow

Entry

Career-Ops Setup Wizard

Choose setup mode:

1. Quick setup with existing CV
2. Guided setup without existing CV
3. Resume existing setup
4. Exit

Quick setup with existing CV

This path is for users who already have a CV.

Inputs:

• CV text pasted into terminal, or
• local .md / .txt file path
• full name
• email
• location / timezone
• target roles
• seniority
• remote / hybrid / on-site preference

Outputs:

• creates cv.md
• creates or fills config/profile.yml
• creates or fills modes/_profile.md
• creates or tunes portals.yml
• creates data/applications.md
• creates data/pipeline.md
• ensures relevant directories exist

Guided setup without existing CV

This path is for users who do not have a ready CV.

Inputs:

• summary
• experience
• projects
• education
• skills
• achievements
• links
• target roles
• location preference

Output:

• generates a starter cv.md
• then continues through the same profile/scanner setup as quick setup

This should create a usable first draft, not a perfect CV.

Optional advanced fine-tuning

After quick or guided setup:

Would you like to add advanced fine-tuning?

1. Yes, customize evaluation/scanner preferences
2. No, finish setup

Advanced options may include:

• role archetypes
• include role keywords
• exclude role keywords
• preferred company types
• remote/location/visa constraints
• salary target and minimum
• deal-breakers
• scoring emphasis
• proof points or portfolio links
• scanner preferences

Resume existing setup

This path should detect existing user-layer files and fill gaps only.

Default behavior:

• skip existing files
• ask before modifying existing files
• ask separately before overwriting any specific file
• optionally back up before overwrite

Example prompt:

config/profile.yml already exists.

Choose an action:
1. Skip
2. Fill missing fields only
3. Overwrite after backup

6. Files Affected

Expected system-layer files

• setup.mjs

  • New local onboarding wizard.
  • Uses Node.js to prompt users and write missing user-layer files.

• package.json

  • Add:

{
  "scripts": {
    "setup": "node setup.mjs"
  }
}

• docs/SETUP.md

  • Mention npm run setup as the recommended beginner path.
  • Keep manual setup available for advanced users.

• docs/SCRIPTS.md

  • Document the new setup command if maintainers prefer script documentation there.

• test-all.mjs

  • Optional. Only touched if maintainers want setup checks included in the existing validation suite.

User-layer files created or updated

• cv.md
• config/profile.yml
• modes/_profile.md
• portals.yml
• article-digest.md if proof points are provided
• data/applications.md
• data/pipeline.md

Directories ensured

• data/
• jds/
• reports/
• output/
• interview-prep/

Files intentionally not modified

• modes/_shared.md
• shared mode files
• core agent instructions
• generated reports
• generated PDFs
• unrelated scripts
• templates as user-specific storage

7. Data Contract Impact

This change introduces a new system-layer script:

• setup.mjs

It also adds a new package script:

• npm run setup

It does not introduce a new required user-owned file beyond files already used by the existing workflow.

Data Contract summary:

• New user file: no mandatory new file beyond existing workflow files
• New optional user file: article-digest.md, only if proof points are provided
• New system file: yes, setup.mjs
• Existing user-layer files affected: yes, only through explicit setup flow
• Existing user data modified automatically: no
• Existing system-layer behavior changed: no
• Existing evaluation logic changed: no
• Existing report parsing changed: no

The wizard should only create or update user-layer files. User-specific preferences should stay in config/profile.yml, modes/_profile.md, portals.yml, cv.md, and optional article-digest.md.

8. Phases

Phase 1 — Quick Setup with Existing CV

Add the smallest useful setup wizard.

Scope:

• Add setup.mjs
• Add npm run setup
• Support pasted CV text
• Support local .md / .txt CV import
• Ask for basic profile fields
• Ask for target roles
• Generate missing user-layer files
• Skip existing files by default
• Run npm run doctor at the end

Acceptance criteria:

• node --check setup.mjs passes
• npm run setup starts the wizard
• pasted CV creates cv.md
• .md / .txt import creates cv.md
• config/profile.yml is created from basic inputs
• modes/_profile.md is created with basic role/evaluation preferences
• portals.yml is created or tuned from target roles
• data/applications.md and data/pipeline.md are created if missing
• existing files are not overwritten by default
• npm run doctor runs at the end

Phase 2 — Guided Setup Without Existing CV

Add a beginner path for users without a prepared CV.

Scope:

• Prompt for summary, experience, projects, education, skills, achievements, and links
• Generate a starter cv.md
• Reuse the same profile/scanner generation from Phase 1

Acceptance criteria:

• guided answers generate a readable starter cv.md
• the generated CV is usable by the rest of Career-Ops
• users can still skip advanced fields

Phase 3 — Advanced Fine-Tuning

Add optional tuning for users who want better evaluation quality.

Scope:

• role archetypes
• include/exclude role keywords
• salary target and minimum
• location/visa/remote constraints
• deal-breakers
• scoring emphasis
• proof points and portfolio links
• scanner preferences

Acceptance criteria:

• advanced inputs update config/profile.yml
• advanced inputs update modes/_profile.md
• scanner preferences update portals.yml
• proof points create or update article-digest.md
• users can skip the whole advanced section

Phase 4 — Resume Existing Setup

Add gap-filling behavior for partially configured users.

Scope:

• detect existing user-layer files
• identify missing required files
• skip existing files by default
• ask before filling missing fields
• ask before overwriting exact files
• optionally create backups before overwrites

Acceptance criteria:

• existing setups are preserved
• missing files can be created
• existing files are never overwritten by accident
• overwrite confirmation is file-specific

Phase 5 — Documentation and Follow-Up Polish

Document the workflow and finalize validation.

Scope:

• update docs/SETUP.md
• optionally update docs/SCRIPTS.md
• add lightweight tests or fixtures if useful
• clarify relationship between npm run setup and npm run doctor

Acceptance criteria:

• beginner setup docs point to npm run setup
• manual setup docs remain available
• doctor remains the validation source of truth

9. Backward Compatibility

Existing users should not be affected.

The wizard should:

1. Create files only when missing.
2. Skip existing files by default.
3. Ask before modifying existing files.
4. Ask separately before overwriting any file.
5. Avoid changing existing evaluation reports, PDFs, or trackers unless the user explicitly chooses to modify setup files.
6. Preserve manual setup as a valid path.

This allows current users to ignore the wizard while new users get a simpler onboarding path.

10. Risks and Mitigations

Risk: Wizard becomes too broad

Mitigation:

• Start with Phase 1 only.
• Keep the first PR focused on CV import + basic profile generation.
• Defer guided CV creation and advanced tuning to follow-up PRs.

Risk: Generated YAML is invalid

Mitigation:

• Use simple deterministic serialization.
• Keep fields conservative.
• Run npm run doctor at the end.
• Avoid free-form YAML editing where possible.

Risk: User files are overwritten accidentally

Mitigation:

• Skip existing files by default.
• Require file-level confirmation before overwrite.
• Optionally back up files before overwrite.

Risk: Setup wizard duplicates doctor logic

Mitigation:

• Treat setup as file creation/filling.
• Treat doctor as validation.
• Run npm run doctor after setup instead of reimplementing validation checks.

Risk: User-specific preferences leak into system-layer files

Mitigation:

• Keep all personalization in user-layer files.
• Do not write user preferences to shared modes or core instructions.

Risk: Guided CV creation creates low-quality CVs

Mitigation:

• Treat guided CV as a starter draft only.
• Keep output simple and editable.
• Avoid claiming it is a polished resume.

11. Test Plan

Manual and automated checks should include:

• node --check setup.mjs
• npm run setup launches successfully
• quick setup with pasted CV creates expected files
• quick setup with .md file import creates expected cv.md
• quick setup with .txt file import creates expected cv.md
• guided setup generates a usable starter cv.md
• advanced setup updates profile.yml, _profile.md, and portals.yml
• existing-file path skips by default
• overwrite path requires explicit confirmation
• required directories are created
• final validation runs npm run doctor
• regression check uses the repo’s existing documented test command

12. Deferred Slices

These should remain out of the first implementation:

• PDF parsing
• DOCX parsing
• browser upload UI
• desktop onboarding UI
• AI-assisted CV parsing
• AI-assisted profile suggestions
• market presets
• language mode selector
• rich company picker
• interactive config editor
• job-board login or authenticated scraping

These can be proposed later once the baseline wizard is accepted.

13. Open Questions

1. Should the first PR implement only Phase 1?
2. Should guided CV creation be part of the first PR or a follow-up?
3. Should article-digest.md be created by default, or only when proof points are provided?
4. Should the wizard fill missing fields inside existing files, or only create files that do not exist?
5. Should overwrites create automatic backups?
6. Should setup use only Node built-ins, or is a small prompt dependency acceptable?
7. Should the wizard live at repo root as setup.mjs, or under a scripts directory?
8. Should npm run setup always run npm run doctor, or ask first?
9. Should docs/SETUP.md, docs/SCRIPTS.md, or both document this command?
10. Should market/language presets be a later RFC instead of part of this wizard?

14. Suggested PR Breakdown

• PR 1: Add setup.mjs, npm run setup, quick CV import, basic user-layer file creation, and doctor handoff.
• PR 2: Add guided CV/profile creation for users without an existing CV.
• PR 3: Add optional advanced fine-tuning for role fit, scanner preferences, deal-breakers, salary, location, and proof points.
• PR 4: Add resume-existing-setup support with safe gap filling and backup/overwrite behavior.
• PR 5: Polish documentation and optional tests.

If maintainers prefer smaller review units, PR 1 can be split into:

• PR 1A: command + file detection + safe write helpers
• PR 1B: quick CV import + profile generation
• PR 1C: portals/data file generation + doctor handoff

[ageem23]

This looks great. Can you include the article-digest.md as part of the automated setup as well