Argus
Argus is a mobile-first library of finite, closed-scope competencies. Each topic has an explicit scored boundary and can be genuinely completed through delayed recall rather than mere exposure.
Argus has two learning interactions:
- Learn — ungraded/formative acquisition. Ordinary topics use reading/exposure and their complete finite reference; progressive topics such as Morse may also use guided formative retrieval, replay and application activities. Learn never creates formal Test evidence; finishing every required lesson once permanently completes a curriculum.
- Test — the single scored recall interaction. Optional after a completed curriculum; an ordinary topic completes with one clean Test.
scope + scored items define the finite Test/completion boundary. Optional topic.learn content is explanatory only and never silently expands that claim.
The current local library format is v5. v5 adds stable item identity, typed item directionality and per-item cue/evidence state while keeping acquisition evidence structurally separate from scheduler/retention history. Older supported libraries migrate forward, and JSON export/import preserves durable learning state. v5 records additionally carry catalog provenance (Topic.origin and the library's catalogDelivered list) so newly shipped topics can be delivered to an existing library without touching anything already in it.
Development
Argus is a Vite + React + TypeScript web app. From the repository root:
npm install
npm run dev
Other commands:
npm run check — run the test suite, type-check, production build and the browser suitenpm run check:quick — type-check and run the unit suite only (fast feedback; does not build or run the browser or Rules suites)npm run check:full — check plus the Firestore Rules suite, i.e. everything CI gates on (needs Java)npm run build — type-check and create the production build in dist/npm run preview — serve the production build locallynpm run typecheck — run TypeScript without buildingnpm run test:browser — run the Playwright suite against the built app at phone, short-landscape and desktop sizes (needs npx playwright install chromium once)npm run test:rules — run the Firestore Security Rules suite against a local emulator (needs Java)npm run inbox:rules — render firestore.rules from its template for the configured exact UID/email pairs (ARGUS_ALLOWED_IDENTITIES)npm run rules:deploy — re-render the rules and deploy them; npm run rules:check refuses a ruleset left behind by the emulator suitenpm run deploy:hosting — build and deploy to Firebase Hostingnpm run build:demo / npm run preview:demo — build the embeddable demo into dist-demo/ and serve it at http://localhost:4174/argus/ (see Demo build)npm run inbox -- list / npm run inbox -- mark-added ... — maintainer content-inbox ingestion
Content inbox
Argus can capture "want to learn" notes into a small Firestore inbox, kept entirely outside the local learning library. It is optional: with no Firebase configuration the capture surface reports itself unavailable and the rest of Argus is unaffected. Copy .env.example to .env.local to configure it. Everything it reads is public web configuration; no privileged credential belongs in the client. See docs/open/CONTENT_INBOX.md.
The production site is https://argus-b7a5a.web.app, on Firebase Hosting. GitHub Pages no longer serves the app, only the embeddable demo (see Demo build); the app is served from the root of its own domain and npm run deploy:hosting is the whole deploy.
Demo build
npm run build:demo (vite build --mode demo) produces an embeddable, local-only copy of Argus for the portfolio. It needs no secrets: .env.demo is committed and blanks every Firebase value, and a demo build ignores Firebase configuration regardless.
- It opens on the shipped catalog with sample progress already on it (the repository's own
seedLibrary() fixture: a drilled NATO alphabet, an OODA loop in learning, a banked bearings topic), so Home and Library are populated on first load.
- It is local by construction: no sign-in, no sync, no inbox and no service worker.
- It never reads or writes the library in browser storage, so a reload always returns to the same sample and a real library under the same origin is never touched. Reset in Profile returns to the sample.
- It is a property of the build, not the URL.
?mode=demo does nothing, and the production build cannot enter demo mode.
- It writes to
dist-demo/, never dist/, so firebase deploy can never upload a demo.
.github/workflows/demo-pages.yml builds it with base /argus/ and publishes it to https://benwassa.github.io/argus/ on every push to main. Pull requests build and check the artifact without deploying. Production is unchanged: Firebase Hosting, deployed by hand with npm run deploy:hosting.
Sync
Signing in with Google keeps the library in step across the owner's own devices. The copy in the browser remains the interaction authority, and signing out leaves that local copy untouched. Where the same topic changed on two devices, neither copy is overwritten — the conflict is reported in Profile.
The production build asks who you are before showing anything, so sign-in is not optional there. A build with no Firebase configuration — what the browser test suite runs against — has nothing to gate and stays entirely local.
The full offline-first runtime guarantee is active scope in #113, not yet a claim about the current localStorage/service-worker implementation. #113 moves canonical persistence to IndexedDB, makes sync intent durable across restart, hardens provisioned-device offline auth startup and makes the production Vite app shell deterministic for cold offline launch. See PRODUCT.md, docs/closed/ISSUE_93_FIREBASE_PROGRESS_SYNC.md and docs/open/ISSUE_113_OFFLINE_FIRST_RUNTIME.md.
Current integration status (2026-10-22)
The Signal-on-Slate overhaul landed on main in #271 with sticky Morse Back follow-up #272. This is repository integration not proof of production deployment or physical Pixel acceptance. The owner/device/release gates remain under #225 and #233. New work should branch from main, not the historical feat/ui-overhaul lane.
The active execution checkpoint tracks three open PRs (#214, #278 and #282) plus superseded PR #222 (closed unmerged), including outstanding source review, and distinguishes the new Morse speed, haptics, Pixel calibration and lesson-completion issues from shipped behavior. The full offline-first guarantee remains open in #113.
Durable product and programme documentation
argus-prd.md is the original July 2026 vision document. Where it describes superseded runtime/schema details, PRODUCT.md and the durable programme documents above govern current implemented behaviour.
Application structure
src/app/ — application composition: providers, routing and the sign-in gatesrc/domain/ — the learning model and the rules over it, with no React in
it: library/ (topics, items, shipped catalog), study/ (scheduling, the
journey, the cue ladder, practice) and morse/ (the code, its curriculum and
its acquisition profile). Two modules here do touch the browser —
morse/audio.ts for Web Audio and morse/curriculum/lessonSittingStorage.ts
for the retired sitting sidecar — and are the exceptions, not the rulesrc/features/ — the surfaces a learner sees, one folder per featuresrc/services/ — application services: sync/, inbox/ and the library
provider. inbox/ is a boundary that imports nothing from the learning librarysrc/infrastructure/ — persistence/: parsing, migration and the local
library repositorysrc/shared/ — UI and layout used across features- Layer boundaries are enforced by
src/architecture.test.ts, which is what keeps
the folders above meaning something: dependencies run domain -> infrastructure
-> services -> features -> app, the domain holds no React, and no feature
reaches inside another
src/styles/ — global tokens and baseline stylesscripts/ — maintainer tooling: rules rendering and content-inbox ingestionfirestore/ — Firestore Security Rules tests, run against the emulatorpublic/ — static PWA assets copied directly into the build
Deployment
Firebase Hosting is the sole deployment target, at the root of its own domain. CI (.github/workflows/validate.yml) runs tests and a build sanity check on every push and pull request, but does not deploy; shipping is a deliberate manual step:
npm run deploy:hosting # dist/ -> Firebase Hosting
npm run rules:deploy # render + deploy Firestore Security Rules
npm run rules:deploy needs ARGUS_ALLOWED_IDENTITIES set to a JSON array of exact {uid, email} pairs; see .env.example. Alternate email spellings are not inferred.
