WorkWingman documentation¶
Every topic here is written in two tracks:
technical/— full detail for engineers (architecture, APIs, code references, diagrams).plain/— everyday language with analogies, for anyone.
Same topics, two depths. Both stay in sync when the code changes. Diagrams are Mermaid so they render on GitHub.
Start here¶
How it happened¶
Three views of the same history, cross-linked so you can hop between them:
- The ledger — delivery board: active sprint, every delivered epic, ticket → commit. Each epic links to its chapter in the story.
- The narrative — the making-of journal (technical · plain): why and how, prompt by prompt, with board backlinks at each chapter.
- The checkpoints — the merge audit that found the apply vertical unwired, and SECURITY.md for the current scanning posture.
- The validation log — real-tenant validation records for Workday, Greenhouse, and iCIMS; the platform-automation research behind the selectors; and the first-push checklist.
- The discovery log —
docs/discovery/holds working drafts and predeclared experiments that are not documentation of how the app works, so they carry no two-track twin: the persona × journey first draft (WING-485/WING-467, for advisor + team markup) and the onboarding-concierge v0 experiment. When a draft becomes a shipped capability, create a newtechnical/+plain/documentation pair; retain the original draft indiscovery/as the proposal record.
| I want to… | Technical | Plain |
|---|---|---|
| See the WING-202 desktop + cloud release scope | WING-202 release | WING-202 release |
| Understand what it is | overview | overview |
| See how it's built | architecture | architecture |
| Know why desktop, cloud, phone, Mac and Linux share one codebase | repo-topology-multi-target | repo-topology-multi-target |
| Run it on my machine | getting-started | getting-started |
| Build/share the installer .exe | packaging | packaging |
| Build the macOS (Apple Silicon) desktop app | macos-desktop-build | macos-desktop-build |
| Know the accounts it uses | connections & SSO | connections & SSO |
| Bring my own API key / link an account | integration-keys | integration-keys |
| Choose which AI (Claude/Codex/Gemini/Grok/Ollama/cloud key) it uses, or add one | llm-harness | llm-harness |
| Understand its safety | security | security |
| See how it's tested | testing | testing |
| Check accessibility for screen readers | a11y-verification | a11y-verification |
| Do a screen-reader walkthrough | — | a11y-walkthrough-checklist |
| Understand the scraper/automation learnings | scraper-automation-learnings | scraper-automation-learnings |
| Call/understand the API | api-reference | api-reference |
| Understand job enrichment signals | job-signals | job-signals |
| See every application-form question type WorkWingman recognizes | application-question-taxonomy | application-question-taxonomy |
| See what the app still needs to ask you, and why each question is separate | profile-data-gaps | profile-data-gaps |
| How resume upload works, and why both screens share one reader | resume-import | resume-import |
| Understand salary & diversity signals | comp-signals | comp-signals |
| See employer insurance + gender-affirming-care signals | benefits-insight | benefits-insight |
| Compare cost of living + take-home pay across cities | col-tax | col-tax |
| See stock-grant valuation (RSUs/options) | equity-comp | equity-comp |
| Work through an offer — accept, negotiate, or wait | offer-review-design | offer-review-design |
| Translate military experience + find federal jobs (planned, not built) | veteran-vertical-design | veteran-vertical-design |
| Prep for an interview with company research | company-research | company-research |
| See historical news vs. realized stock moves | news-price-context | news-price-context |
| Read a company's recent health before applying | company-health | company-health |
| Compare housing/commute costs across cities | lifestyle-costs | lifestyle-costs |
| Compare family costs across cities | family-costs | family-costs |
| Understand financial history & job-impact comparisons | financial-profile | financial-profile |
| Prep for a coding assessment | assessment-prep | assessment-prep |
| Prep for the interview itself | interview-prep-bank | interview-prep-bank |
| Research interviewers & find common ground | interviewer-research | interviewer-research |
| Finish a degree faster with credit-by-exam | degree-completion planner | degree-completion planner |
| Understand study videos & podcasts | study-media | study-media |
| Generate narrated audio overviews | audio-harness | audio-harness |
| Contribute | contributing | contributing |
| Understand why CI kept failing on the self-hosted runner (and how it was fixed) | ci-self-hosted-runner | ci-self-hosted-runner |
| Read the build story | making-of | making-of |
| See the cross-ATS scraper learnings | scraper-automation-learnings-summary | scraper-automation-learnings-summary |
| Find every link | references | references |
| See which AI dev-tools we allow, how they are pinned, and what we refused | mcp-dev-tooling | mcp-dev-tooling |
| Weigh A2UI generative UI | a2ui-assessment | a2ui-assessment |
| Pick a stock price data source | stock-data-sources | stock-data-sources |
| Weigh PageAgent vs. Playwright | pageagent-feasibility | pageagent-feasibility |
| Use an AI as a second opinion on tricky form fields | pageagent-advisor-design | pageagent-advisor-design |
| Turn study notes into portable MP3s/MP4s | study-audio | study-audio |
| Take the optional self-assessment suite | self-assessment | self-assessment |
| Understand the guild calendar and inbox design | guild calendar/inbox decisions | guild calendar/inbox decisions |
| See what evidence a recommendation must provide | recommendation fit requirements | recommendation fit requirements |
| Study the WING-193 cloud deployment work | WING-193 cloud study guide | WING-193 cloud study guide |
| Review the WING-404 council items still deferred | WING-404 council follow-ups | WING-404 council follow-ups |
| Practice for a role (LeetCode + platforms) | learning-paths | learning-paths |
| See free community/prep resources matched to demographics | demographic-resources | demographic-resources |
| Prep studio (LeetCode company libraries, richer Claude projects, phone flashcards) | prep-studio | prep-studio |
| Coach WE-focused interview answers | interview-coaching | interview-coaching |
| Draft outreach to a recruiter/hiring manager | outreach-drafting | outreach-drafting |
| Handle the post-interview loop (thank-you, retro, question bank) | interview-retro | interview-retro |
| Understand per-tenant ATS accounts (the "create an account" wall) | ats-accounts | ats-accounts |
| Export/back up your data (Excel + Drive) | data-backup | data-backup |
| Send prep into NotebookLM (optional) | notebooklm | notebooklm |
| Generate original AI study illustrations | study-visuals | study-visuals |
| See the AI-generation strategy (lanes, costs, caps WING-299, packs WING-300) | ai-generation-strategy | ai-generation-strategy |
Business & strategy¶
How WorkWingman becomes a durable, help-people-first business — and eventually the
"Common App for jobs." Detailed track lives in business/; everyday
mirrors live in plain/. Produced by a multi-model council + dedicated research
agents (see council-verdict).
| I want to… | Detailed | Plain |
|---|---|---|
| Get the whole plan | business README | business-overview |
| Pitch it in one breath | elevator-pitch | elevator-pitch |
| See the whole thing on one page | executive-summary | business-overview |
| Understand how we make money | monetization-strategy | money-plan |
| See the staged plan over time | roadmap | roadmap |
| Check pricing, costs, ROI, break-even | financial-model · .xlsx | money-plan |
| Understand the cloud cost model in everyday terms | — | cloud costs |
| Read the plain-language landing-page message | — | landing copy |
| Present to an investor/partner | pitch-deck · .pptx | — |
| Know how we grow & stay trusted | gtm-positioning | how-we-grow |
| Understand the legal/compliance guardrails | legal-compliance-risk | staying-legal-and-safe |
| See where the strategy came from | council-verdict | — |
Diagrams¶
Three layers, all committed as source + rendered output (see diagrams/):
inline Mermaid in the docs, a C4 model set (Context / Container / Component) rendered from
D2 to SVG for the technical track, and a hand-drawn sketch flow for the
plain track. CI re-renders and fails if a committed SVG is stale.
About these docs¶
They're meant to double as a learning resource: someone should be able to read them and learn how to build something like this from scratch. Every library, framework, API, and tool is linked to its official docs and source; patterns and techniques come with "learn more" pointers. See references / references.
The making-of is a living document — the full prompt-by-prompt story of how the app was built, updated as it grows.