coulomb-social/workplans/CSOC-WP-0004-app-shell-and-space-content.md

---
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/<slug>/`, 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/`