Add documentation for undocumented features (#172)
* documentation writing skill * visa sponsors page * overview * in progress board * settings * reactive resume section * database backups * workflows * post application tracking flow * manual tracking caveats * pricing section * pipeline run detalis * job search bar * keyboard shortcuts * bulk actions * no informal phrasing * formatting * build fix? * Update docs-site/docs/features/overview.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update docs-site/versioned_docs/version-0.1.20/features/orchestrator.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update docs-site/docs/features/visa-sponsors.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update docs-site/docs/features/in-progress-board.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * remove link to page that don't exist --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
This commit is contained in:
Shaheer Sarfaraz
co-authored by
Copilot
Copilot
parent
1f929dfc7f
commit
390d03625e
@@ -5,7 +5,27 @@ description: Technical index of supported extractors and how they work.
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
Technical breakdowns of each extractor:
|
||||
This page helps you choose the right extractor for your run, understand key constraints, and navigate to detailed technical guides.
|
||||
|
||||
## Extractor chooser
|
||||
|
||||
| Extractor | Best use case | Core constraints/dependencies | Notable controls | Output/behavior notes |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| [Gradcracker](/docs/extractors/gradcracker) | UK graduate roles from Gradcracker | Crawling stability depends on page structure and anti-bot behavior; tuned for low concurrency | `GRADCRACKER_SEARCH_TERMS`, `GRADCRACKER_MAX_JOBS_PER_TERM`, `JOBOPS_SKIP_APPLY_FOR_EXISTING` | Scrapes listing metadata, then detail pages and apply URL resolution |
|
||||
| [JobSpy](/docs/extractors/jobspy) | Multi-source discovery (Indeed, LinkedIn, Glassdoor) | Requires Python wrapper execution per term; source availability and quality vary by site/location | `JOBSPY_SITES`, `JOBSPY_SEARCH_TERMS`, `JOBSPY_RESULTS_WANTED`, `JOBSPY_HOURS_OLD`, `JOBSPY_LINKEDIN_FETCH_DESCRIPTION` | Produces JSON per term, then orchestrator normalizes and de-duplicates by `jobUrl` |
|
||||
| [UKVisaJobs](/docs/extractors/ukvisajobs) | UK visa sponsorship-focused roles | Requires authenticated session and periodic token/cookie refresh | `UKVISAJOBS_EMAIL`, `UKVISAJOBS_PASSWORD`, `UKVISAJOBS_MAX_JOBS`, `UKVISAJOBS_SEARCH_KEYWORD` | API pagination + dataset output; orchestrator de-dupes and may fetch missing descriptions |
|
||||
| [Manual Import](/docs/extractors/manual) | One-off jobs not covered by scrapers | Inference quality depends on model/provider and input quality; some URLs cannot be fetched reliably | App/API endpoints (`/api/manual-jobs/infer`, `/api/manual-jobs/import`) | Accepts text/HTML/URL, runs inference, then saves and scores job after review |
|
||||
|
||||
## Which extractor should I use?
|
||||
|
||||
- Use **JobSpy** for broad first-pass sourcing across common boards.
|
||||
- Use **Gradcracker** when targeting graduate pipelines in the UK.
|
||||
- Use **UKVisaJobs** for sponsorship-specific UK searches.
|
||||
- Use **Manual Import** when you already have a specific posting and need direct import.
|
||||
|
||||
Many runs combine sources: broad discovery first, then manual import for high-priority jobs that scraping misses.
|
||||
|
||||
## Related extractor docs
|
||||
|
||||
- [Gradcracker](/docs/extractors/gradcracker)
|
||||
- [JobSpy](/docs/extractors/jobspy)
|
||||
|
||||
@@ -5,30 +5,37 @@ description: Context-aware per-job AI chat assistant behavior and API surface.
|
||||
sidebar_position: 2
|
||||
---
|
||||
|
||||
Ghostwriter is the per-job AI chat assistant in JobOps.
|
||||
## What it is
|
||||
|
||||
## What it is for
|
||||
Ghostwriter is the per-job AI chat assistant in JobOps.
|
||||
|
||||
Ghostwriter uses:
|
||||
|
||||
- Current job description and metadata
|
||||
- Reduced profile snapshot
|
||||
- Global writing style settings
|
||||
- current job description and metadata
|
||||
- reduced profile snapshot
|
||||
- global writing style settings
|
||||
|
||||
The UI behavior is one persistent conversation per job, shown in the right-side drawer from job details.
|
||||
|
||||
## Why it exists
|
||||
|
||||
Ghostwriter helps you produce job-specific writing quickly while preserving consistency with your profile and style settings.
|
||||
|
||||
Typical use cases:
|
||||
|
||||
- Role-specific answer drafting
|
||||
- Cover letter and outreach drafts
|
||||
- Interview prep tied to the JD
|
||||
- Rephrasing with tone constraints
|
||||
- role-specific answer drafting
|
||||
- cover letter and outreach drafts
|
||||
- interview prep tied to the job description
|
||||
- rephrasing with tone constraints
|
||||
|
||||
## Where it appears
|
||||
## How to use it
|
||||
|
||||
- Available from job details in `discovered` and `ready`
|
||||
- Right-side drawer UX
|
||||
- One persistent conversation per job
|
||||
1. Open a job in `discovered` or `ready`.
|
||||
2. Open the Ghostwriter drawer.
|
||||
3. Enter your prompt and stream a response.
|
||||
4. Stop or regenerate responses when needed.
|
||||
|
||||
## Writing style settings impact
|
||||
### Writing style settings impact
|
||||
|
||||
Global settings affecting generations:
|
||||
|
||||
@@ -44,14 +51,14 @@ Defaults:
|
||||
- Constraints: empty
|
||||
- Do-not-use terms: empty
|
||||
|
||||
## Context and safety model
|
||||
### Context and safety model
|
||||
|
||||
- Job snapshot is truncated to fit prompt budget.
|
||||
- Profile snapshot includes relevant slices only.
|
||||
- System prompt enforces read-only assistant behavior.
|
||||
- Logging stores metadata, not full prompt/response dumps.
|
||||
|
||||
## API surface
|
||||
### API surface
|
||||
|
||||
- `GET /api/jobs/:id/chat/messages`
|
||||
- `POST /api/jobs/:id/chat/messages` (streaming)
|
||||
@@ -59,3 +66,26 @@ Defaults:
|
||||
- `POST /api/jobs/:id/chat/messages/:assistantMessageId/regenerate` (streaming)
|
||||
|
||||
Compatibility thread endpoints remain, but UI behavior is one thread per job.
|
||||
|
||||
## Common problems
|
||||
|
||||
### Responses feel too generic
|
||||
|
||||
- Verify the job description is complete and current.
|
||||
- Confirm style constraints in Settings are specific enough.
|
||||
|
||||
### Generation quality is lower than expected
|
||||
|
||||
- Check model/provider configuration in Settings.
|
||||
- Tighten prompts with explicit output intent (for example, "3 bullet points for recruiter outreach").
|
||||
|
||||
### Missing context in answers
|
||||
|
||||
- Update profile data and relevant project details used by Ghostwriter context.
|
||||
- Regenerate after updating job notes/description.
|
||||
|
||||
## Related pages
|
||||
|
||||
- [Orchestrator](/docs/features/orchestrator)
|
||||
- [Post-Application Tracking](/docs/features/post-application-tracking)
|
||||
- [Troubleshooting](/docs/troubleshooting/common-problems)
|
||||
|
||||
@@ -5,88 +5,114 @@ description: Job states, ready flow, and PDF generation/regeneration behavior.
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
This guide explains job states, how jobs become ready, and how PDF generation works.
|
||||
## What it is
|
||||
|
||||
## Job states
|
||||
The Orchestrator is the primary jobs workspace in JobOps.
|
||||
|
||||
- `discovered`: Found by crawler/import, not tailored yet.
|
||||
- `processing`: Tailoring and/or PDF generation in progress.
|
||||
- `ready`: Tailored PDF generated and ready to apply.
|
||||
- `applied`: Marked as applied.
|
||||
- `skipped`: Explicitly excluded from active queue.
|
||||
- `expired`: Deadline passed.
|
||||
It controls:
|
||||
|
||||
## Intended ready flow
|
||||
- job lifecycle states
|
||||
- manual and automatic ready flow
|
||||
- PDF generation and regeneration
|
||||
- handoff to post-application tracking
|
||||
|
||||
### 1) Manual flow
|
||||
Job states:
|
||||
|
||||
1. Job starts in `discovered`.
|
||||
2. Open in Discovered panel and choose Tailor.
|
||||
3. Edit JD/tailored fields/project picks.
|
||||
4. Click **Finalize & Move to Ready**.
|
||||
- `discovered`: found by crawler/import, not tailored yet
|
||||
- `processing`: tailoring and/or PDF generation in progress
|
||||
- `ready`: tailored PDF generated and ready to apply
|
||||
- `applied`: marked as applied
|
||||
- `skipped`: explicitly excluded from active queue
|
||||
- `expired`: deadline passed
|
||||
|
||||
### 2) Auto flow
|
||||
## Why it exists
|
||||
|
||||
1. Pipeline scores discovered jobs.
|
||||
2. Top jobs above threshold are auto-processed.
|
||||
3. Jobs move directly to `ready` with generated PDFs.
|
||||
Orchestrator centralizes the transition from discovered opportunities to application-ready artifacts.
|
||||
|
||||
## Ghostwriter
|
||||
It exists to ensure:
|
||||
|
||||
- a consistent path from discovery to tailored output
|
||||
- clear status transitions across manual and automated workflows
|
||||
- predictable regeneration behavior when job data changes
|
||||
|
||||
## How to use it
|
||||
|
||||
### Intended ready flow
|
||||
|
||||
1. Manual flow:
|
||||
1. Job starts in `discovered`.
|
||||
2. Open the job and choose Tailor.
|
||||
3. Edit JD/tailored fields/project picks.
|
||||
4. Click **Finalize & Move to Ready**.
|
||||
2. Auto flow:
|
||||
1. Pipeline scores discovered jobs.
|
||||
2. Top jobs above threshold are auto-processed.
|
||||
3. Jobs move directly to `ready` with generated PDFs.
|
||||
|
||||
### Ghostwriter availability
|
||||
|
||||
Ghostwriter is available in `discovered` and `ready` job views.
|
||||
|
||||
For details, see [Ghostwriter](/docs/features/ghostwriter).
|
||||
|
||||
## Generating PDFs (first time)
|
||||
### Generating PDFs
|
||||
|
||||
PDF generation uses:
|
||||
|
||||
- Base resume selected from RxResume
|
||||
- Job description
|
||||
- Tailored summary/headline/skills/projects
|
||||
- base resume selected from RxResume
|
||||
- job description
|
||||
- tailored summary/headline/skills/projects
|
||||
|
||||
Common paths:
|
||||
|
||||
- **Discovered → Tailor → Finalize**
|
||||
- `POST /api/jobs/:id/process`
|
||||
- **Ready → Regenerate PDF**
|
||||
- `POST /api/jobs/:id/generate-pdf`
|
||||
- Discovered to finalization: `POST /api/jobs/:id/process`
|
||||
- Ready regeneration: `POST /api/jobs/:id/generate-pdf`
|
||||
|
||||
## Regenerating PDFs after edits
|
||||
### Regenerating PDFs after edits (copy-pasteable examples)
|
||||
|
||||
If JD or tailoring changes, regenerate PDF to keep output in sync.
|
||||
|
||||
### API flow
|
||||
|
||||
```bash
|
||||
PATCH /api/jobs/:id
|
||||
{
|
||||
"jobDescription": "<new JD>",
|
||||
"tailoredSummary": "<optional>",
|
||||
"tailoredHeadline": "<optional>",
|
||||
"tailoredSkills": "[{\"name\":\"Backend\",\"keywords\":[\"TypeScript\",\"Node.js\"]}]",
|
||||
"selectedProjectIds": "p1,p2"
|
||||
}
|
||||
curl -X PATCH "http://localhost:3001/api/jobs/<jobId>" \
|
||||
-H "content-type: application/json" \
|
||||
-d '{
|
||||
"jobDescription": "<new JD>",
|
||||
"tailoredSummary": "<optional>",
|
||||
"tailoredHeadline": "<optional>",
|
||||
"tailoredSkills": [{"name":"Backend","keywords":["TypeScript","Node.js"]}],
|
||||
"selectedProjectIds": "p1,p2"
|
||||
}'
|
||||
```
|
||||
|
||||
```bash
|
||||
POST /api/jobs/:id/summarize?force=true
|
||||
POST /api/jobs/:id/generate-pdf
|
||||
curl -X POST "http://localhost:3001/api/jobs/<jobId>/summarize?force=true"
|
||||
curl -X POST "http://localhost:3001/api/jobs/<jobId>/generate-pdf"
|
||||
```
|
||||
|
||||
## Post-application tracking
|
||||
|
||||
For inbox routing flow and setup, see [Post-Application Tracking](/docs/features/post-application-tracking).
|
||||
|
||||
## Notes and gotchas
|
||||
|
||||
- `processing` is transient. On PDF failure, job reverts to `discovered`.
|
||||
- PDFs are served at `/pdfs/resume_<jobId>.pdf` with cache-bust on `updatedAt`.
|
||||
- `skipped`/`applied` jobs can be reopened by patching `status` to `discovered`.
|
||||
|
||||
## External payload and sanitization defaults
|
||||
### External payload and sanitization defaults
|
||||
|
||||
- LLM prompts send minimized profile/job fields.
|
||||
- Webhooks are sanitized and whitelisted by default.
|
||||
- Logs and error details are redacted/truncated by default.
|
||||
- Correlation fields include `requestId`, and when available `pipelineRunId` and `jobId`.
|
||||
|
||||
## Common problems
|
||||
|
||||
### Job is stuck in `processing`
|
||||
|
||||
- `processing` is transient; failures generally revert the job to `discovered`.
|
||||
- Check run logs and retry generation.
|
||||
|
||||
### PDF does not reflect recent edits
|
||||
|
||||
- Run summarize with `force=true` after changing the JD/tailoring.
|
||||
- Regenerate PDF after summarize completes.
|
||||
|
||||
### Reopen skipped/applied jobs
|
||||
|
||||
- Patch `status` back to `discovered` to return the job to the active queue.
|
||||
|
||||
## Related pages
|
||||
|
||||
- [Ghostwriter](/docs/features/ghostwriter)
|
||||
- [Post-Application Tracking](/docs/features/post-application-tracking)
|
||||
|
||||
@@ -1,34 +0,0 @@
|
||||
---
|
||||
id: documentation-style-guide
|
||||
title: Documentation Style Guide
|
||||
description: Standards for writing user-facing docs in this repository.
|
||||
sidebar_position: 2
|
||||
---
|
||||
|
||||
Use this structure for feature pages:
|
||||
|
||||
1. **What it is**
|
||||
2. **Why it exists**
|
||||
3. **How to use it**
|
||||
4. **Common problems**
|
||||
5. **Related pages**
|
||||
|
||||
## Frontmatter requirements
|
||||
|
||||
Every doc should include:
|
||||
|
||||
- `id`
|
||||
- `title`
|
||||
- `description`
|
||||
- `sidebar_position`
|
||||
|
||||
## Writing rules
|
||||
|
||||
- Prefer concrete steps over abstract prose.
|
||||
- Provide copy-pasteable examples.
|
||||
- State defaults and constraints explicitly.
|
||||
- Link related docs using `/docs/...` URLs.
|
||||
|
||||
## PR expectations
|
||||
|
||||
Any user-visible behavior change should include matching docs updates.
|
||||
|
||||
Reference in New Issue
Block a user