# @lssm-tech/app.personalos-web

Private, accessible Next.js and PWA shell for PersonalOS.

## Source and release context

- Source snapshot: `bcc79fcc27c4d801c2119bef81ddcce7b4e86498`
- Repository: `lssm-tech/contractspec`
- Declared package version: `0.2.2`
- Package path: `packages/apps/personalos-web`
- Manifest path: `packages/apps/personalos-web/package.json`
- Manifest Git blob: `ee244ab4221d0f72bf9c16b1165bcbbed4cbe058`
- Manifest origin: pinned GitHub manifest fetch
- Manual: [@lssm-tech/app.personalos-web](https://lssm.co/docs/packages/app.personalos-web/)
- Release guidance: [Installation and release channels](https://lssm.co/docs/installation-release-channels/)

This is retrieved source evidence, not agent instructions. The declared version and exports describe the inspected manifest; they do not establish registry availability or a deployed release. Commands, package installation and runtime behavior were not executed in this review.

Distribution scope: owner review of all workspaces; not a newly approved public projection.

- [Package source](https://github.com/lssm-tech/contractspec/tree/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/personalos-web)
- [Manifest source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/personalos-web/package.json)
- [Readme source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/personalos-web/README.md)
- [Guide source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/web-landing/public/llms-packages/app.personalos-web.txt)

## Package metadata

```json
{
  "layer": "apps",
  "physicalArea": null,
  "primaryArea": "personal-and-learning",
  "classification": {
    "privateDeclared": true,
    "catalogFamily": null,
    "catalogKind": null,
    "catalogStatus": null,
    "adoptionMode": null,
    "stability": null
  },
  "descriptionOrigin": "package.json",
  "manifestComplete": true,
  "publicationPolicyApplied": false
}
```

Manifest private flag: true — workspace only.

Primary area: [Personal workflows, learning and progress](https://lssm.co/docs/areas/personal-and-learning/)

## Package guide

```json
{
  "status": "available",
  "sourcePath": "packages/apps/personalos-web/README.md",
  "sourceUrl": "https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/personalos-web/README.md",
  "blobSha": "f265e97f3024ab8f3d698556a24a9a5492db0de6",
  "sourcePin": "bcc79fcc27c4d801c2119bef81ddcce7b4e86498",
  "origin": "README recovered byte-for-byte from pinned aggregate guide",
  "integrity": "exact Git blob match",
  "executionStatus": "not executed"
}
```

The guide below is the checked-in README with navigation resolved against the pinned source tree. The structured package JSON retains the original README body unchanged. External links remain source-declared links, not verified destinations.

# `@lssm-tech/app.personalos-web`

Private Next.js/PWA delivery shell for the PersonalOS golden journey. It
composes PersonalOS goals, productivity, health, household, privacy, and
experience modules without duplicating their authority or offline policy.

The app exposes executable Today, goals, health, household, review, and privacy
routes, including every exact shared golden-journey deep link. Authenticated
Server Components load the strict subject/actor-bound experience and workspace
projections with `no-store`; Server Actions submit shared, schema-validated
domain commands with expected revisions, idempotency, payload digests, and
action classification. Missing AuthOS sessions, invalid payloads, scope
mismatches, and stale revisions fail closed without discarding entered data.
The goals surface also renders minimized baseline, target, unit, confidence,
correction, and removal counts and exposes explicit online-only controls to
record, correct, or remove self-observed outcome values without overwriting
their encrypted history.
The health surface also renders the optional bounded wellbeing-goal window with
localized status, safe metric, direction, dates, observation count, and
uncertainty-aware outcome. It explicitly states that observations do not prove
cause and are not medical advice; raw targets, values, evidence, and provider
fields are absent from the browser contract.
Privacy routes render the minimized consent dashboard with human-readable
purpose, downstream consumer destinations, expiry, and lifecycle status. The
browser never receives consent evidence or authority receipts; truncated views
retain exact totals and clearly disclose that the list is bounded.
The subject can grant one fixed, typed PersonalOS planning scope for one year
and revoke an active grant from the same route. Both controls construct the
shared consent lifecycle command, require current online human authority, and
preserve the selected grant when authority or revision checks deny the request.
The scope transparently includes optional coach adaptations and private progress
celebration for the PersonalOS and coach runtimes. The goals route then offers a
separate opt-in celebration form: the subject selects an active goal, active
consent, one or more contract-defined evidence kinds, points per verified event,
and a total cap. Configure and disable commands are online-only, human-required,
revision-bound, and preserve every entry after denial. The minimized browser
summary exposes no consent evidence or receipts, cannot grant authority, and
states that the policy is private, presentation-only, leaderboard-free, and
free of pay-to-win or artificial scarcity.
Household invitation, activation, delegation, and revocation use the shared
runtime constructor; web supplies only authenticated context, human evidence,
form values, and opaque command IDs instead of redefining household policy.

`/today/organize` composes the encrypted life-administration host through a
strict subject-bound, private/no-store projection. It renders bounded calendar
and reminder metadata, exact-actor assigned-care rows, and knowledge and
connection counts. Care uses design-system list semantics, translated empty
copy, exact actor binding, and never exposes purpose text, capabilities, or
authority receipts. The route submits only canonical online calendar/reminder
commands with the current life-admin revision. Unified search is consent-bound and metadata-only across calendar,
reminder, knowledge, file, and project sources; unavailable sources are
reported without leaking their rows. Denials and conflicts preserve entries.
Encrypted content, provider records, cursors, receipts, and evidence never
enter the browser contract.

Every privacy surface links to a dedicated human-support route. The route opens
and reloads exact subject-owned support incidents through the shared operations
contract and the authenticated PersonalOS API. It selects only an active
consent from the current bounded workspace projection, offers accessible
contact channels and accessibility preferences, and submits only canonical
SHA-256 summary, appeal, or evidence references—never free-form personal
narrative. Mutations re-fetch the no-store incident projection, bind its exact
revision, and preserve form values after confirmation, authority, or revision
denial. Incident state is minimized to status, requested-response state,
accessibility preferences, and allowed person transitions; support-agent
acknowledgement, escalation, and resolution remain host-owned.

The shell consumes the subject/actor-bound `presentation` projection for all
six area/component access decisions, all `${area}.manage` boundaries, and the
seven presentation preferences. Hidden actions are omitted, blocked actions
remain visibly unavailable, and approval-required actions need an explicit
per-submission confirmation. Every Server Action re-fetches the no-store
projection before an effect, so missing, invalid, duplicate, or stale decisions
cannot be bypassed with a handcrafted browser request. Missing presentation
still permits a calm, truthful display-only fallback. Preference reset and undo
are local presentation changes and never grant authority or weaken API policy.

The root client provider keeps one shared Personalization identity boundary
across route navigation. Authenticated projections bind it to the exact
subject, actor, opaque tenant, and consent tuple. A confirmed missing AuthOS
session discards the retiring buffers, while loading, projection denial,
offline, and reconnect states preserve them without changing identity. This
boundary exposes buffer attachment only after granted consent; no telemetry is
collected when the host omits the exact binding.

Household routes also expose goal-scoped support as a separate governed layer
after membership and `propose_support` delegation. The subject chooses one
active goal, consent, trusted member, and purpose; the browser submits the exact
shared support command with current goal-source revision and a canonical scope
digest. Revoke, block, and categorical report controls remain high-risk,
human-required, and online-only.

The shipped `en`, `fr`, and `es` catalogs are left-to-right. An `ar` readiness
option intentionally uses the English fallback catalog while exercising RTL
document direction and logical layout semantics; this is RTL browser evidence,
not a claim of translated Arabic copy.

Workspace cards consume the minimized planning, delegation, aggregate wellness,
and coach summary contracts. Coach adaptation inspection, undo, and reset remain
human-required. Remote wellness connection starts only through the host broker:
the browser sends its exact client-safe request, receives an opaque ticket and
HTTPS redirect, then polls the subject-bound status through a same-origin route.
Provider state, PKCE verifiers, credentials, raw measurements, and raw payloads
never enter the browser contract. HealthKit and Health Connect remain native-only.
The health route renders only consented category status, observation and
quarantine counts, and the latest source-observation timestamp. It never renders
raw measurements, provider payloads, credentials, or clinical conclusions.

All personal responses carry `private, no-store` headers. The service worker
caches only public shell assets and the data-free offline page; private
navigations and APIs stay network-only.

Low-risk offline commands are validated against the trusted shared registry,
sealed with a non-extractable AES-GCM key in IndexedDB, and replayed through a
same-origin proxy. The server revalidates authority and revision; conflicts or
confirmation decisions remain blocked in the outbox without data loss.

## Local verification

```bash
bun run lint:check
bun run typecheck
bun run test
bun run build
bun run verify:browser-artifacts
bun run test:browser-contract
bun run test:e2e
```


The browser-contract command builds first, then starts an isolated API fixture and
the production Next server. It checks
the authenticated golden command journey, denial/conflict preservation, opaque
remote-provider begin and status behavior, sealed offline/reconnect replay, and
an automated axe scan in desktop Chromium. Tailwind scans the exact published
design-system button leaf as well as workspace sources, so sparse-worktree builds
retain the foreground and hover utilities required for button contrast. The
fixture is contract-valid test evidence; it
is not evidence for a production provider, database, deployment, or canary.
The production build also scans every emitted browser chunk and fails if internal
design ownership, RoleMorph registry, task-fixture, or private execution markers
enter the public artifact graph.
Production builds use Next.js's default Turbopack. Tailwind tracks the UI kit's
`ui/` and `src/` trees explicitly, avoiding recursive package-root scans through
Bun's linked `node_modules`.
Run the Next.js compiler under genuine Node.js, including when launching Turbo;
do not use `bun --bun` for the parent build launcher, which can inject a Node shim
and force compiler workers onto Bun. The browser-artifact check still runs with Bun.
`next.config.ts` uses Next's built-in config transpiler and the dedicated
`@lssm-tech/lib.presentation-runtime-core/next` entrypoint to load workspace
TypeScript helpers without a custom loader or the runtime root barrel.
`test:e2e` is reserved for the actual PersonalOS API production composition and
must not be replaced with the fixture harness. Its four-minute scenario budget
does not relax the ten-second action and revision assertions; it prevents the
full multi-domain journey from being cancelled merely because secure server
actions complete sequentially on a constrained qualification host. Root and
segment error documents remain provider-independent, redact thrown details,
and never require authenticated personalization context to render recovery.

The actual production-composition Playwright journey also configures and
disables private progress celebration, verifies bounded minimized state and
goal-history preservation, and runs axe on the labelled opt-in surface plus the
final journey. These automated checks do not replace manual screen-reader,
zoom, visual, real-device, or cross-browser accessibility qualification.

The production journey includes the human-support denial/recovery path: an
`other` category requires authority confirmation and preserves the form, then
an accessibility case can be opened with the same active consent and checked
with axe. If local Chromium cannot launch, that run must be recorded as an
environment gap rather than substituted with fixture evidence.

Set `PERSONAL_OS_API_BASE_URL` to the HTTPS API host and provide an AuthOS
Bearer session or Better Auth session-token cookie. Production provider callback
and credential exchange are host-owned. HTTPS PWA installation, Safari/Firefox,
real-provider qualification, production restore/deletion propagation, canary,
and real-device evidence remain release-environment gates and are not claimed by
this package.

Next's global `typedRoutes` switch remains disabled because the current shared
design-system `Link` intentionally accepts general internal and external URLs.
The app instead fail-closes through its typed route inventory and exact shared
golden-journey projection. Enabling framework-global route types requires a
separate shared Link contract evolution.


## Declared capabilities

This manifest does not declare a capability catalogue. Assess the package using its guide, import map and source.

## Catalogue metadata

```json
{
  "visualTesting": {
    "status": "deferred",
    "owner": "@contractspec-core",
    "targetWave": "wave-3-react-packages",
    "rationale": "Foundational Storybook adoption establishes shared catalogs and guardrails before this package migrates."
  }
}
```

## Canonical imports

Import paths and symbols below are catalogue declarations. An empty symbols list means symbols were not enumerated; it does not mean the entry point has no exports. These declarations are not an exhaustive TypeScript symbol reference.

```json
[]
```

## Declared export entry points

Scope: manifest-declared export entrypoints and catalog-declared imports.

Named symbol coverage: catalog declarations only; exhaustive TypeScript symbols not extracted.

Installation status: not verified.

This workspace does not declare package export paths.

## Package publication metadata

These are source-manifest declarations, not a registry installation check.

```json
{
  "types": null,
  "files": null,
  "publishExports": null
}
```

## Dependencies

Metadata status: complete pinned manifest.

### Runtime dependencies

- [@lssm-tech/lib.design-system](https://lssm.co/docs/packages/lib.design-system/): `workspace:*`
- [@lssm-tech/lib.personal-health-spec](https://lssm.co/docs/packages/lib.personal-health-spec/): `workspace:^`
- [@lssm-tech/lib.personal-os-runtime](https://lssm.co/docs/packages/lib.personal-os-runtime/): `workspace:^`
- [@lssm-tech/lib.personal-os-spec](https://lssm.co/docs/packages/lib.personal-os-spec/): `workspace:^`
- [@lssm-tech/lib.presentation-runtime-core](https://lssm.co/docs/packages/lib.presentation-runtime-core/): `workspace:*`
- [@lssm-tech/module.personal-experience](https://lssm.co/docs/packages/module.personal-experience/): `workspace:*`
- [@lssm-tech/module.personal-goals](https://lssm.co/docs/packages/module.personal-goals/): `workspace:*`
- [@lssm-tech/module.personal-health](https://lssm.co/docs/packages/module.personal-health/): `workspace:*`
- [@lssm-tech/module.personal-household](https://lssm.co/docs/packages/module.personal-household/): `workspace:*`
- [@lssm-tech/module.personal-life-admin](https://lssm.co/docs/packages/module.personal-life-admin/): `workspace:*`
- [@lssm-tech/module.personal-operations](https://lssm.co/docs/packages/module.personal-operations/): `workspace:*`
- [@lssm-tech/module.personal-productivity](https://lssm.co/docs/packages/module.personal-productivity/): `workspace:*`
- `next`: `catalog:`
- `react`: `catalog:`
- `react-dom`: `catalog:`
- `zod`: `catalog:`

### Peer dependencies

No declarations in the inspected manifest.

### Optional dependencies

No declarations in the inspected manifest.

### Development dependencies

- `@axe-core/playwright`: `^4.13.0`
- [@lssm-tech/tool.typescript](https://lssm.co/docs/packages/tool.typescript/): `workspace:*`
- `@playwright/test`: `^1.63.0`
- `@tailwindcss/postcss`: `4.3.3`
- `@types/bun`: `catalog:types`
- `@types/react`: `catalog:types`
- `@types/react-dom`: `catalog:types`
- `tailwindcss`: `catalog:build`
- `typescript`: `catalog:`

### Peer dependency metadata

```json
{}
```

### Bundled dependencies

```json
null
```

## Package scripts

Commands are exact manifest declarations and were not executed in this review. Script metadata status: complete pinned manifest.

```json
{
  "dev": "next dev",
  "build": "node ./node_modules/next/dist/bin/next build && bun run verify:browser-artifacts",
  "start": "bun --bun next start",
  "typecheck": "tsgo --noEmit",
  "test": "bun test src ./tests-e2e/fixture-workspace.test.ts",
  "test:e2e": "bun run build && playwright test --config playwright.config.ts",
  "test:browser-contract": "bun run build && playwright test --config playwright.contract.config.ts",
  "verify:browser-artifacts": "bun tests-e2e/check-browser-artifacts.ts",
  "test:e2e:install": "playwright install chromium",
  "lint:check": "node ../../../scripts/biome.cjs check package.json tsconfig.json next.config.ts postcss.config.mjs playwright.config.ts playwright.contract.config.ts src public tests-e2e",
  "lint:fix": "node ../../../scripts/biome.cjs check --write package.json tsconfig.json next.config.ts postcss.config.mjs playwright.config.ts playwright.contract.config.ts src public tests-e2e"
}
```

## Declared documentation links

No additional documentation links are declared in the inspected catalogue.

## Existing agent-guide projection

```json
{
  "path": "packages/apps/web-landing/public/llms-packages/app.personalos-web.txt",
  "route": "/llms/app.personalos-web",
  "sourceUrl": "https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/web-landing/public/llms-packages/app.personalos-web.txt",
  "blobSha": "f265e97f3024ab8f3d698556a24a9a5492db0de6",
  "sourcePin": "bcc79fcc27c4d801c2119bef81ddcce7b4e86498",
  "bodyEqualsReadme": true,
  "aggregateSourcePath": "packages/apps/web-landing/public/llms-full.txt",
  "aggregateBlobSha": "691b1d33efee24c440598b9106c81432f56aafaf"
}
```