--- id: CSOC-WP-0004 type: workplan title: "App shell entry and Forgejo-backed space content" domain: communication repo: coulomb-social status: finished owner: bernd topic_slug: coulomb-social created: "2026-08-10" updated: "2026-08-12" # note: T07 added same day — principal diagnostics via profile menu depends_on: - CSOC-WP-0002 related: - CSOC-WP-0001 - CSOC-WP-0003 origin: operator origin_ref: session-2026-08-10-parallel-host-product-path state_hub_workstream_id: "d10427aa-02d9-4ec9-a466-d7cdb1a9167e" --- # CSOC-WP-0004 — App shell entry and Forgejo-backed space content ## Context Identity is live on **`https://app.coulomb.social`**. After Sign in, members land on an identity **confirmation shell** (“Signed in” + principal dump) with no product surface. Bubble on apex remains the full product until we choose cutover. **Goal for this phase:** build the new implementation toward product usefulness **before** bulk Bubble data migration. Immediate product foundation: 1. Leave the login confirmation shell into a real **app home**. 2. Establish **space** persistence whose **content is markdown**, stored and versioned in close connection with **Forgejo** repositories. Migration of all Bubble spaces is **explicitly later** (`CSOC-WP-0001`). **Finished 2026-08-12:** T01–T07 complete. Operator runbook and smoke pointers in `docs/deploy.md` and `docs/identity/smoke.md`. ## Out of scope (this plan) - Apex DNS cutover / Bubble retirement - Full Bubble inventory or bulk import - Public self-registration (CSOC-WP-0003 residuals / NetKingdom) - Full UI parity (Research, marketplace matching, …) beyond space content MVP --- ## T01 — Post-login product entry (leave confirmation shell) ```task id: CSOC-WP-0004-T01 status: done priority: high state_hub_task_id: "7cce67c0-6234-4ef4-ad67-de952f5f4519" ``` Replace the dead-end “Signed in / Principal” page as the primary post-login destination with an **app home** that a member can use: - Clear primary navigation: Spaces (and placeholders for later surfaces). - Compact account control (display name / avatar) opening a **profile menu** (full principal diagnostics live under **T07**, not on the home body). - Empty state when the member has no spaces yet (“Create space” or “No spaces”). - `LOGIN_REDIRECT_URL` and templates updated; design-extract tokens only as needed. **Done when:** after OIDC login on app.coulomb.social, tegwick lands on app home (not a debug-only principal card) and can navigate without guessing URLs. 2026-08-11: App home is Spaces empty state; header nav + profile menu; principal dump removed from home body. Deploy with next image for app.coulomb.social. ## T02 — Space domain model (metadata, tenant-keyed) ```task id: CSOC-WP-0004-T02 status: done priority: high state_hub_task_id: "5fd91718-151d-4216-acf2-2104a45cddf9" ``` Introduce `Space` (name pending Bubble vocabulary alignment) as application metadata in the app DB: - `tenant_id`, stable slug, display title, owner/membership linkage to Member - **no** long-form page bodies in Postgres as the system of record - optional pointer fields for content binding (repo, default branch, root path) Migrations + admin + minimal list/detail routes behind auth. **Done when:** authenticated user can list zero-or-more spaces from DB; tests cover tenant isolation basics. 2026-08-12: `spaces` app — `Space` + `SpaceMembership`, tenant-scoped list on `/app/`, detail `/app/spaces//`, admin seed path. Tests cover isolation. ## T03 — Content model ADR: markdown + Forgejo ```task id: CSOC-WP-0004-T03 status: done priority: high state_hub_task_id: "628243e0-732f-42c1-b4e3-9b8cd82ea530" ``` Write `docs/adr/ADR-0002-space-content-forgejo-markdown.md` deciding: - Markdown (and assets) as the **canonical content form** for space pages - Forgejo repo layout (one repo per space vs monorepo paths; branch policy) - How the app **reads** content (clone/cache, raw API, webhook invalidation) - How the app **writes** (direct git push as service account vs user OAuth to Forgejo) - Relationship to Bubble page/chunk model for later CSOC-WP-0001 mapping - Secrets: Forgejo tokens via OpenBao / env secret names only **Done when:** ADR accepted (or explicitly provisional with open questions listed) and linked from INTENT/SCOPE. 2026-08-12: Provisional ADR-0002 committed; linked from INTENT/SCOPE. One repo per space, `pages/` root, Forgejo API read for T04; write-in-Forgejo for T05. ## T04 — Read path: render space markdown from bound repo ```task id: CSOC-WP-0004-T04 status: done priority: high state_hub_task_id: "77fa3454-6f2e-4a76-8a0c-ff7e13ca4b6a" ``` Implement a vertical slice: - Operator or seed binds one space to a Forgejo repo path - App fetches/renders a markdown page (e.g. `README.md` or `pages/index.md`) - Authz: member of tenant/space only (flex-auth or coarse membership check) - Fail closed on missing binding or fetch errors **Done when:** tegwick can open a space on app.coulomb.social and see rendered markdown sourced from Forgejo (not Bubble). 2026-08-12: Forgejo raw fetch + bleach-sanitized markdown render; demo fixture at `docs/space-fixtures/demo/pages/index.md`; `seed_demo_space` management command; env `FORGEJO_BASE_URL` / optional `FORGEJO_TOKEN`. ## T05 — Write / sync path (minimal) ```task id: CSOC-WP-0004-T05 status: done priority: medium state_hub_task_id: "30ed5def-2718-4379-834c-920e751e4d0b" ``` Minimal authoring or sync so content is not read-only forever: - either in-app edit → commit to Forgejo, or - documented “edit in Forgejo / pull request” workflow + refresh webhook Prefer the smaller path that keeps git as source of truth. **Done when:** a content change in Forgejo appears in the app without redeploy, and (if in-app write exists) a save produces a commit without secrets in git. 2026-08-12: **Edit in Forgejo** + **View source** + **Refresh content** on space detail; repo-scoped cache invalidate; optional push webhook `POST /app/spaces/hooks/forgejo/` (HMAC or shared secret). Docs: `docs/spaces-content.md`. No in-app editor (git remains SoR). ## T06 — Seed and runbook for app.coulomb.social ```task id: CSOC-WP-0004-T06 status: done priority: medium state_hub_task_id: "40a880d0-62b9-4ae4-ab3e-074e8901462a" ``` Document operator steps: create Forgejo org/repo, bind space, credentials env names, smoke checklist on app.coulomb.social. Update `docs/deploy.md` and `docs/identity/smoke.md` pointers as needed. 2026-08-12: Full operator runbook in `docs/deploy.md` (demo seed, dedicated repo, webhook, env table, smoke table). Product smoke section in `docs/identity/smoke.md`. FORGEJO_* names in `.env.example` and `docs/dev.md`. Content detail remains `docs/spaces-content.md`. ## T07 — Principal diagnostics via user profile menu ```task id: CSOC-WP-0004-T07 status: done priority: high state_hub_task_id: "8487443a-dfd2-4220-a90b-bca2b5b04c4c" ``` Keep the current principal card fields available as **detail information** reachable from the **user profile menu** in the app chrome (not as the primary post-login page body). Purpose: refine and diagnose identity wiring during ongoing user, group, role, and tenant management work. Include at least the present shell fields (and extend as claims become available): | Area | Examples | |------|----------| | Identity | display name, username, issuer, subject | | Platform user | user-engine id, user-engine source | | Tenancy | tenant id / claims | | Roles & groups | OIDC/groups/roles claims when present | | Authz | flex-auth / shell decision reason + decision id | | Session | assurance / AAL hints when present | UX: - Profile menu entry e.g. **Account** / **Session details** / **Identity** - Detail view at a stable path (e.g. `/account/` or `/account/session/`) - Readable for operators; no secrets (tokens, proxy secrets) ever rendered - Sign out remains on the menu **Done when:** after T01 app chrome exists, tegwick can open the profile menu → principal/session detail page and see the same diagnostic surface formerly on the signed-in card, without that card being the home page. Ship with or immediately after **T01** (same PR is fine). 2026-08-11: `/account/session/` holds principal diagnostics (identity, UE, tenant, roles/groups, assurance, authz). Profile menu → **Session details**. Session stashes groups/roles/assurance at login (no secrets). --- ## Sequencing ```text T01 app home entry ──┬─► T07 profile menu principal diagnostics └─► T02 Space metadata └─► T03 content ADR └─► T04 read path (MVP value) ├─► T05 write/sync └─► T06 runbook ``` ## Acceptance (workplan) 1. Post-login journey is product-shaped (app home + spaces), not identity-debug-only. 2. Principal/session diagnostics remain available from the user profile menu (T07). 3. Spaces exist as tenant-keyed app records. 4. Space page content is markdown backed by Forgejo with a working read path. 5. Bubble migration is still not required for demos on app.coulomb.social. 6. CSOC-WP-0001 can map Bubble pages onto the ADR layout when migration starts. 7. Operator runbook documents seed, bind, secrets (names), and smoke (T06). ## Related - Live host: `docs/deploy.md` (app.coulomb.social parallel to Bubble) - Identity: CSOC-WP-0002 (done), CSOC-WP-0003 residuals for public registration - Migration later: CSOC-WP-0001 - Design tokens: `docs/design-extract/`