coulomb/coulomb-social
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Record architecture decisions: thin git plane, live default, upgrades

Browse source 
D1 thin dir+git with shard-wiki then kontextual upgrade path; D2 defer
asset-store; D3 NetKingdom authz consolidation; D4 outline explode/implode
and live-by-default includes with pin as exception.
This commit is contained in:
tegwick 2026-08-13 00:48:33 +02:00
parent c27a50e6d3
commit d953aed4dd
5 changed files with 232 additions and 210 deletions
Download patch file Download diff file Expand all files Collapse all files

368
docs/architecture/ArchitectureBlueprint.md
View file

@ -2,31 +2,21 @@
| Field | Value | | Field | Value |
|-------|--------| |-------|--------|
| Status | **draft for discussion** (revised 2026-08-13) | | Status | **draft — decisions recorded 2026-08-13** |
| Product | coulomb.social rebuild (`coulomb-social`) | | Product | coulomb.social rebuild (`coulomb-social`) |
| Related | stage-1 cut, capability maps, substrate exploration, authoring, stale/derived | | Related | stage-1 cut, capability maps, authoring, stale/derived, upgrade path |
| Non-goals | Final store vendor lock-in; full UI chrome; implementing markitect features in this doc | | Non-goals | Implementing UI chrome here; full markitect feature build in this doc |
## 0. Review summary (2026-08-13) ## 0. Decision log (2026-08-13)
This revision folds in topics settled after the first draft: | # | Topic | Decision |
|---|--------|----------|
| D1 | **Content plane** | **Start thin:** directory + markdown files, **secured in git**. Supported **upgrade path**: thin → **shard-wiki** (when wiki/federation matters) via markitect-shaped content; then → **kontextual** (structure, scale, rich media) as a **supported upgrade** of the information base. |
| D2 | **asset-store** | **Extract later.** Stage-1 may use local files next to markdown (and/or temporary blob helpers); do not block on a new repo. |
| D3 | **PolicyGateway / content authz ownership** | **Do not invent a parallel owner.** Prefer **NetKingdom consolidation** so identity *and* authorization decisioning for app resources become the obvious path (flex-auth / NK as one story). Until that lands, coulomb uses coarse product authz (session + SpaceMembership + tenant); content plane stays fail-closed when a PDP is wired. |
| D4 | **Structure UX** | Aspire to **outline-editor flexibility**: **explode** one markdown into smaller **connected** documents; **implode** selection(s) back into one file. **Default = live** (spreadsheet-like: includes/derived resolve to current inputs automatically). **Pin** only when the user freezes a snapshot. |
| Topic | Stance | Earlier freezes (unchanged): NetKingdom identity, Railiance deploy, markdown SoR + DB cache, markitect-tool not host, page-first, dual authoring, lazy projections + lock, stage-1 cut.
|-------|--------|
| Identity / tenants / groups | NetKingdom only |
| Deploy | Railiance |
| Content SoR | Markdown + assets; DB = cache |
| markitect | **tool** as structure lib; **not** “run on markitect”; **main** = legacy |
| Page vs chunk | **Page-first**; chunks = address / transclude / promote |
| Authoring | Top-down **and** bottom-up; no forced mode |
| Title / Abstractor / Visual | Real fields; may start **lazy**; then persist; **regenerate + lock** |
| Stale derived content | Badge → generate **alternative** → **replace or keep** |
| Includes | Live resolve **and** (proposed) pinned snapshots with same stale grammar |
| Content plane | Still open: thin store / shard-wiki / kontextual (spikes) |
| Assets | kontextual BlobStorage now; extract asset-store when 2nd consumer |
| Live Bubble | Mapped; S1 aligns with Title/Abstractor/Visual/spaces/pages/cards |
**Still open (decisions, not re-litigate principles):** content-plane pick (A/B/C), visual storage short-term, PolicyGateway owner, chunk migration strategy.
--- ---
@ -36,62 +26,66 @@ Deliver a co-creation product where:
1. **Identity** (users, groups, tenants) is **NetKingdom** — not reimplemented. 1. **Identity** (users, groups, tenants) is **NetKingdom** — not reimplemented.
2. **Runtime** is **Railiance** — not reimplemented. 2. **Runtime** is **Railiance** — not reimplemented.
3. **User-owned content** is **markdown (+ assets)** exportable without the app database. 3. **User-owned content** is **markdown (+ assets)** in a **git-secured directory tree**, exportable without the app database.
4. The **database is a cache / projection** for cards, memberships, search speed. 4. The **database is a cache / projection** for cards, memberships, search speed.
5. **markitect-tool** makes markdown an efficient structured substrate (lib/CLI/API) — **not** the product host. 5. **markitect-tool** makes markdown structured and operable (parse, include, explode/implode, later derived slots) — **not** the product host.
6. **coulomb** owns co-creation UI (cards, spaces, copy/transfer, authoring UX) and product verbs. 6. **coulomb** owns co-creation UI (cards, spaces, outline-oriented editing, copy/transfer).
7. Knowledge work stays **fluent**: top-down and bottom-up authoring; structure and reuse appear when needed (transclusion, lazy projections), not as mandatory a priori chunk graphs. 7. Knowledge work stays **fluent**: top-down and bottom-up; **live** reuse by default; pin when freezing matters.
8. Growth does not strand data: **thin git base → shard-wiki → kontextual** are **supported upgrades**, not rewrites from a proprietary store.
## 2. Non-negotiable rules ## 2. Non-negotiable rules
| # | Rule | | # | Rule |
|---|------| |---|------|
| R1 | Markdown (frontmatter + body + backmatter) + assets are the **exportable SoR** for content. | | R1 | Markdown (frontmatter + body + backmatter) + assets under a **directory tree** are the **exportable SoR**. |
| R2 | App DB holds **projections and app linkage only** for content; disposable for bodies. | | R2 | App DB holds **projections and app linkage only**; disposable for content bodies. |
| R3 | Authn/IdP = **NetKingdom**; coulomb maps OIDC → Member; no password store. | | R3 | Authn/IdP = **NetKingdom**; coulomb maps OIDC → Member; no password store. |
| R4 | Authz composes NetKingdom groups, app membership, content-plane ACLs — **no second user directory**. | | R4 | Authz: prefer **NetKingdom-consolidated** decisioning; no second user directory; no permanent coulomb-specific PolicyGateway fiefdom. |
| R5 | **markitect-main** is legacy reference, not a runtime foundation. | | R5 | **markitect-main** is legacy reference, not a runtime foundation. |
| R6 | **markitect-tool** is the markdown structure dependency (parse, validate, query, include, later derived slots). | | R6 | **markitect-tool** is the markdown structure dependency. |
| R7 | Content plane (shard-wiki / kontextual / thin store) sits behind a **narrow PageOps** interface. | | R7 | **Default content plane = thin dir+git.** PageOps hide the plane; upgrades swap adapters. |
| R8 | Stage-1 must: onboarding; spaces/pages with **Title / Abstractor / Visual**; page copy; page transfer. | | R8 | Stage-1 must: onboarding; spaces/pages with **Title / Abstractor / Visual**; page copy; page transfer. |
| R9 | **Pages first** — do not model documents as a priori chunk assemblies; use address/transclude/promote. | | R9 | **Pages first** — address / live-transclude / explode-implode / promote; not a priori chunk storage. |
| R10 | Derived content (projections, pinned includes, pipelines, AI) uses **stale badge → alternative → replace\|keep** and **lock**; no silent overwrite of locked/user content. | | R10 | **Live by default** for includes and other formula-like derived content; **pin** freezes a snapshot; pinned/stale use badge → alternative → **replace \| keep** + lock. |
| R11 | **Explode / implode** (outline-editor flexibility) are first-class structure operations (markitect primitives + coulomb UX). |
| R12 | **asset-store** extraction is **deferred**; assets may live beside markdown until then. |
## 3. System shape ## 3. System shape
```text ```text
┌──────────────────────────┐ ┌──────────────────────────┐
│ NetKingdom │ │ NetKingdom │
│ OIDC, groups, tenants │ │ OIDC · groups · tenants│
│ (authz consolidation →)│
└────────────┬─────────────┘ └────────────┬─────────────┘
│ principal │ principal
▼ ▼
┌─────────────────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────────────┐
│ coulomb.social (product) │ │ coulomb.social (product) │
│ • Card UI, spaces chrome, dual authoring flows │ │ • Cards, spaces, dual authoring, outline explode/implode │
│ • Session / Member / SpaceMembership │ │ • PageOps; live resolve; pin when asked │
│ • PageOps + projection UX (lazy / stale / lock) │
│ • Railiance deploy │ │ • Railiance deploy │
└───────────────┬─────────────────────────────┬───────────────┘ └───────────────┬─────────────────────────────┬───────────────┘
│ projections │ content ops │ cache │ PageOps
▼ ▼ ▼ ▼
┌───────────────┐ ┌───────────────────────────┐ ┌───────────────┐ ┌───────────────────────────┐
│ App DB cache │ │ Content plane (adapter) │ │ Postgres │ │ Content plane │
│ (Postgres) │ │ A thin folder/git │ │ projections │ │ ★ A thin dir + git │
└───────────────┘ │ B shard-wiki (thin) │ └───────────────┘ │ (default / stage-1) │
│ C kontextual-engine │ │ ↗ B shard-wiki upgrade │
│ ↗ C kontextual upgrade │
└─────────────┬─────────────┘ └─────────────┬─────────────┘
│ structure │
▼ ┌─────────────▼─────────────┐
┌───────────────────────────┐
│ markitect-tool │ │ markitect-tool │
│ parse, FM, query, include │ │ structure · include LIVE │
│ derived/stale (proposed) │ │ explode/implode · query │
│ pin/derived (proposed) │
└─────────────┬─────────────┘ └─────────────┬─────────────┘
▼ ▼
┌───────────────────────────┐ ┌───────────────────────────┐
│ Asset bytes (blobs) │ │ Assets (files next to md) │
│ content-addressed │ │ later: shared asset-store │
└───────────────────────────┘ └───────────────────────────┘
``` ```
@ -99,188 +93,210 @@ Deliver a co-creation product where:
| Op | Meaning | | Op | Meaning |
|----|---------| |----|---------|
| `list_pages(space)` | Card projections | | `list_pages` / `get_page` / `put_page` / `archive_page` | CRUD |
| `get_page(id)` | Full markdown + resolved visual; optional include resolve | | `copy_page` / `transfer_page` | Duplicate / re-home |
| `put_page(...)` | Create/update attributes + body | | `explode_page` / `implode_pages` | Outline-style split/join (markitect) |
| `archive_page` | Soft-delete / lifecycle | | `resolve_view` | Live includes/derived for display (default) |
| `copy_page` | Independent duplicate (rewrite includes as needed) | | `pin_slot` / `unpin` / `refresh_pinned` | Freeze snapshot; stale → alternative → replace\|keep |
| `transfer_page` | Re-home to another space | | `project_field` / `regenerate` / `lock` | Title/abstractor/visual lifecycle |
| `put_visual` / `get_asset` | Binary visual/attachment | | `put_visual` / `get_asset` | Binary next to tree (later asset-store) |
| `project_field` / `regenerate` / `lock` | Lazy & stale projection actions |
| `derived_refresh` | Stale include/pipeline: alternative → replace\|keep (when markitect supports) |
Coulomb templates/services do **not** call Forgejo/shard/kontextual APIs ad hoc — only PageOps. ### Upgrade path (supported)
```text
Stage now A dir + .md + assets (+ git)
│ markitect-tool always
│
When wiki / B same markdown becomes shard-wiki shard(s)
federation │ PageOps adapter swap; export tree still valid
│
When scale / C kontextual KnowledgeAsset + blobs
rich media / │ markdown remains portable representation
governance │ PageOps adapter swap; migration tooling required
```
**Requirement:** every upgrade **preserves user export** of markdown+assets; no dead-end proprietary body store.
## 4. Information model (product) ## 4. Information model (product)
| Concept | Representation | | Concept | Representation |
|---------|----------------| |---------|----------------|
| **Page** | Markdown: frontmatter (title, abstractor, visual, space, projections lifecycle, …) + body + backmatter | | **Page** | One markdown file (or connected set after explode) |
| **Space** | Container; may be `type: space` page or container id in frontmatter | | **Space** | Directory / container + metadata page |
| **Visual** | Asset ref → blob store | | **Tree** | Git-secured directory layout |
| **Card** | UI only: visual + title + abstractor + actions (+ stale badges) | | **Card** | UI projection (title, abstractor, visual, actions, stale) |
| **Region / “chunk”** | Addressable unit of a page (heading, `mkt:region`, selector) — **not** a required storage type | | **Outline** | Headings / exploded connected docs — **not** Bubble chunk rows |
| **Transclusion** | Live `mkt:include` and/or pinned `mkt:derived` snapshot (proposed) | | **Live include** | `mkt:include` resolves current source (default) |
| **Pinned derived** | Optional frozen snapshot; explicit refresh |
| **Member / tenant** | NetKingdom + app session | | **Member / tenant** | NetKingdom + app session |
### 4.1 Page-first vs Bubble chunks ### 4.1 Outline editor flexibility (explode / implode)
Live Bubble has `custom.chunk` graphs. Rebuild stance: Aspire to outline-editor UX powered by markitect **explode / implode** (and related compose/include):
| Action | User intent | Markitect analogue |
|--------|-------------|-------------------|
| **Explode** | Split a large page into smaller **connected** documents (sections as pages or files) | `mkt explode` (+ connectivity via includes/refs) |
| **Implode** | Merge selected docs/sections **back into one** markdown file | `mkt implode` / compose |
| **Navigate outline** | Treat structure as editable hierarchy | Headings + connected pages view |
Connectivity after explode: prefer **live includes or content references** so the outline stays one logical document until the user pins or permanently severs links.
### 4.2 Live by default (spreadsheet metaphor)
| | Live (default) | Pinned (exception) |
|--|----------------|-------------------|
| Includes / formula-like derived | Resolve to **current** inputs on view/export | Stored snapshot until refresh |
| Body of a normal page | User text as written | n/a |
| Projections (title/abstractor/visual) | Lazy fill then **persist**; regenerate on demand | Lock freezes; stale offers alternative |
| Stale pinned / locked derived | — | Badge → generate alternative → **replace or keep** |
**Spreadsheet rule:** formulas stay live unless the user **pastes values** (pin).
Pinning is deliberate, not the default co-creation mode.
### 4.3 Dual authoring + lazy projections
Unchanged intent: top-down and bottom-up both natural; missing display fields lazy-fill then persist; regenerate + lock per field.
See `authoring-modes-and-lazy-projections.md`, `stale-derived-content.md`.
## 5. Content plane — decided start + upgrades
### 5.1 Default: A — thin directory + git
```text ```text
Write fluently in a page spaces/<space-slug>/
→ address regions when needed pages/<page-slug>.md
→ transclude / extract / promote assets/…
→ materialize a new page only when reuse earns independence # entire tree in git (user- or service-mediated commits)
``` ```
See `transclusion-and-chunks.md`. Migration may flatten Bubble chunks into sections/regions/pages+includes.
### 4.2 Dual authoring
| Mode | Flow |
|------|------|
| **Top-down** | Title → abstractor → outline (headings) → elaborate body → visual |
| **Bottom-up** | Body first; title/abstractor/visual/structure later |
No mandatory mode toggle. Empty body with metadata is valid; body-only is valid.
### 4.3 Lazy projections + lock + stale alternatives
For **title**, **abstractor**, **visual** (and similar display fields):
1. Missing on display need → **generate** (lazy) → **persist** as normal field values.
2. **Regenerate** and **lock** are per-field.
3. If inputs changed → **May be stale** → **Generate updated version** → compare Current \| Alternative → **Keep** or **Use alternative**.
Detail: `authoring-modes-and-lazy-projections.md`, `stale-derived-content.md`.
Same grammar for **pinned includes** and **pipeline/AI/rule** blocks (markitect proposal: `mkt:derived`).
## 5. Content-plane options (comparison)
### 5.1 Option A — Thin folder/git store + markitect-tool
| | | | | |
|--|--| |--|--|
| **Idea** | `.md` tree + assets; markitect validates; app indexes cards | | **Why** | Simplest SoR; user data is files; matches “secured in git” |
| **Pros** | Fastest S1; trivial export; low structure tax | | **coulomb role** | PageOps over filesystem/git; DB indexes cards |
| **Cons** | Copy/transfer/versioning are app work; federation later costs more | | **markitect role** | Parse, live include, explode/implode, validate |
| **When** | Velocity first; plane maturity unclear |
### 5.2 Option B — shard-wiki (thin slice) ### 5.2 Upgrade B — shard-wiki
| | | When multi-shard wiki behavior, overlays, or federation become product-relevant:
|--|--|
| **Idea** | Headless wiki orchestration; IdP external; coulomb = UI |
| **Pros** | Page union, git coordination, multi-shard later; INTENT names Coulomb |
| **Cons** | Structure tax if federation leaks into product; multi-tenant ops still maturing |
| **Thin-slice rule** | One InformationSpace / instance; one primary shard; hide federation from cards |
### 5.3 Option C — kontextual-engine - Ingest the **same** markdown tree (or git repo) as a shard.
- PageOps adapter targets shard-wiki; UI unchanged.
- markitect-tool remains structure layer for resolve/explode.
| | | ### 5.3 Upgrade C — kontextual-engine
|--|--|
| **Idea** | Knowledge ops: asset identity, representations, blobs, audit, workflows; markdown via markitect adapter |
| **Pros** | Blobs ready; lineage; multi-format future; PolicyGateway port |
| **Cons** | Heavier; NetKingdom not wired; must enforce markdown export as happy path |
| **Auth gap** | Map OIDC → Actor; PolicyGateway → flex-auth |
### 5.4 Evolution (not exclusive forever) When asset identity, scale, rich multi-format media, audit/lineage, or ECM-class governance dominate:
```text - Supported **migration** of the information base into kontextual assets/blobs.
PageOps → A or thin B/C now - Markdown remains the portable authoring/export form where applicable.
→ folder/git shard can become shard-wiki - **Not** required for stage-1.
→ assets can move to kontextual / asset-store
→ markitect-tool always structure layer
```
**Working shortlist (unchanged):** spike **A** as control + **B thin** and **C** in parallel; pick after scorecard (`spike-checklist.md`). ### 5.4 What we do *not* do now
## 6. Asset management - Do not build coulomb **on** markitect-main.
- Do not require kontextual or shard-wiki for first productive transfer.
- Do not extract **asset-store** before a second consumer (D2).
| Source | Role | ## 6. Assets (deferred extract)
|--------|------|
| kontextual BlobStorage | Prefer for Visual/bytes now (fs/S3/memory, content-addressed) |
| markitect-main assets | Ideas only — do not runtime-depend |
| Extract `asset-store` | When **second** consumer needs same API; seed from kontextual port |
Visual field stores a **ref** (path or `sha256:…`); bytes never live only in Postgres. - Stage-1: files under `assets/` (or equivalent) in the content tree; optional simple content-addressing later.
- **asset-store** shared repo: **later** (seed from kontextual BlobStorage when extracted).
- Visual field stores a **ref** into that tree (or future store).
## 7. Identity & access control ## 7. Identity & access control
```text ```text
Browser → NetKingdom OIDC → coulomb session Browser → NetKingdom OIDC → coulomb session
├─ product authz: tenant_id, SpaceMembership ├─ product: tenant_id, SpaceMembership (and future NK groups)
└─ content plane: Actor(external_ref=iss|sub, groups=…) └─ long-term: NetKingdom-consolidated authz (flex-auth / NK)
PolicyGateway → flex-auth (preferred) so PolicyGateway ownership becomes trivial or unused
``` ```
Fail closed on ambiguous access. Spike: OIDC → Actor → cross-tenant deny. | Now | Target |
|-----|--------|
| Session + membership + tenant isolation | Same + NK-group claims |
| Content plane fail-closed if PDP present | PDP = consolidated NK story |
| No coulomb-owned IdP | Unchanged |
**D3:** Avoid multi-team thrash on “who owns PolicyGateway”; push consolidation in NetKingdom so apps only pass principal + resource attributes.
## 8. Deploy sketch (Railiance) ## 8. Deploy sketch (Railiance)
| Component | Deploy | | Component | Deploy |
|-----------|--------| |-----------|--------|
| coulomb-social | Existing chart; `app.coulomb.social` | | coulomb-social | Existing chart; `app.coulomb.social` |
| Content plane | In-process, sidecar, or platform service | | Content tree | Volume or git-backed storage accessible to the app; **git** is SoR discipline |
| Asset bytes | PVC and/or S3; secrets via env-secret pattern | | Assets | Beside markdown until asset-store |
| NetKingdom | Existing KeyCape / Authelia | | NetKingdom | Existing KeyCape / Authelia |
Apex DNS stays Bubble until stage-1 cut + transfer readiness. ## 9. Stage-1 product scope
## 9. Stage-1 product scope (capability cut) **Must:**
**Must for productive transfer** (Bubble → reference-only): - Onboarding (NetKingdom)
- Spaces/pages: Title, Abstractor, Visual, body
- Copy, transfer
- Cards; dual authoring; lazy projections
- Content as **dir+git** via PageOps
- Live includes when markitect is wired; pin optional
- Member onboarding (NetKingdom; public reg may lag via provisioned users) **Aspire early (structure UX):**
- Spaces + pages with **Title, Abstractor, Visual** + markdown body
- Page **copy** and **transfer**
- Card presentation
- Dual authoring + lazy projections (at least title/abstractor); stale replace|keep preferred early
**Later:** social, ventures/invest, challenges marketplace, monetization, full chunk-stage machine, multi-shard personal vaults. - Outline-oriented **explode / implode**
Live Bubble map: `docs/capability/existing-bubble-capability-map.md`. **Later:** social, marketplace, monetization, shard-wiki/kontextual upgrades, asset-store extract.
## 10. ADR roadmap ## 10. ADR roadmap
| ADR | Topic | | ADR | Topic |
|-----|--------| |-----|--------|
| ADR-0001 | NetKingdom identity (**done**) | | ADR-0001 | NetKingdom identity (**done**) |
| ADR-0002 | Forgejo binding — **demote** to one adapter/export shape | | ADR-0002 | Forgejo slice → **one optional git remote / export**, not unique SoR |
| **ADR-0003** | Page-centric model + SoR + DB cache + page-first/transclusion | | **ADR-0003** | Page model + dir+git SoR + page-first + live default + authoring/stale |
| **ADR-0004** | Content-plane choice + PageOps | | **ADR-0004** | PageOps + **thin plane** + **upgrade path** B/C |
| **ADR-0005** | Asset-store extraction (if/when) | | **ADR-0005** | asset-store extraction (**later**) |
| **ADR-0006** | Authoring modes + projections + stale/derived (or fold into 0003) | | — | NetKingdom authz consolidation (NK work, not coulomb-owned forever) |
Markitect-tool: implement `proposed-stale-derived-and-include-pinning.md` as its own work. Markitect-tool: live include (done), explode/implode (done), pin/derived proposal (`proposed-stale-derived-and-include-pinning.md`).
## 11. Spike checklist ## 11. Spikes (narrowed)
See **[spike-checklist.md](./spike-checklist.md)**. With D1–D4, prioritize:
Add when scheduling: dual-authoring smoke, stale projection compare UX, include pin (after markitect).
## 12. Discussion prompts (remaining) 1. **Thin tree layout + git write path** (PageOps on files).
2. **markitect** parse + **live** include in get/view.
3. **Explode/implode** UX prototype on real pages.
4. **Lazy title/abstractor** + stale replace\|keep.
5. Export zip/tar of tree without DB.
1. Content plane for next 3–6 months: **A velocity**, **B federation path**, or **C governance/blobs**? Defer deep shard-wiki/kontextual spikes except **export/import round-trip sketches** that prove upgrade feasibility.
2. Visual: kontextual/local blob first, or block on asset-store extract?
3. PolicyGateway production owner?
4. Bubble **chunk** migration: sections/regions only, or keep a chunk list UX as a *view*?
5. Default include mode in product: **live** vs **pinned** for shared excerpts?
## 13. Working recommendation (principles frozen; plane open) Full list remains in `spike-checklist.md` (update scorecard: A = chosen start).
| Layer | Recommendation | ## 12. Closed discussion prompts
|-------|----------------|
| Product UI | coulomb cards + spaces + dual authoring | | Prompt | Resolution |
| Markdown structure | markitect-tool (includes + future derived slots) | |--------|------------|
| Identity / deploy | NetKingdom / Railiance | | A vs B vs C for start | **A**; B/C = supported upgrades |
| Content plane | Spike A+B+C; choose with export fidelity as hard constraint | | asset-store now? | **Later** |
| SoR | Markdown export always works; engines add IDs/lineage without trapping content | | PolicyGateway owner | **Consolidate under NetKingdom**; don’t fork ownership |
| Assets | kontextual blobs now; extract later if shared | | Chunk UX | **Outline editor + explode/implode**, not chunk tables |
| Chunks | Transclusion/extract, not a priori graph | | Live vs pin default | **Live**; pin is explicit |
| Derived/stale | Badge → alternative → replace\|keep + lock |
---
## 13. Working recommendation (frozen)
| Layer | Decision |
|-------|----------|
| Product UI | coulomb cards, spaces, outline explode/implode, dual authoring |
| Markdown structure | markitect-tool; **live** includes by default |
| Identity / deploy | NetKingdom / Railiance; authz → NK consolidation |
| Content plane | **Thin dir + git** now |
| Upgrades | → shard-wiki → kontextual (supported, markdown-preserving) |
| Assets | Beside tree now; **asset-store later** |
| Derived/stale | Live default; pin + badge → alternative → replace\|keep |
| markitect-main | Avoid | | markitect-main | Avoid |
--- ---
@ -301,7 +317,7 @@ Add when scheduling: dual-authoring smoke, stale projection compare UX, include
### fleet ### fleet
- kontextual: architecture-blueprint, asset-registry, blob-storage, markitect reuse boundary - markitect-tool: transform-compose-include, explode-implode, content-references, **proposed-stale-derived-and-include-pinning.md**
- shard-wiki: INTENT, SCOPE - shard-wiki: INTENT (Coulomb as consumer; upgrade target)
- markitect-tool: transform-compose-include, content-references, cache-incremental, **proposed-stale-derived-and-include-pinning.md** - kontextual: blob-storage, asset-registry (upgrade + later asset-store seed)
- markitect-main: successor-gap-assessment (legacy) - markitect-main: successor-gap (legacy only)

35
docs/architecture/spike-checklist.md
View file

@ -150,32 +150,23 @@ Scoring legend for each spike: **Pass** / **Partial** / **Fail** / **Skip** with
--- ---
## Spike 8 — Cross-option decision workshop ## Spike 8 — Decision workshop → **mostly closed 2026-08-13**
**Owner:** founder + implementers **Recorded in ArchitectureBlueprint §0 (D1–D4):**
**Depends on:** Spikes 1–6 results
- [ ] Fill scorecard (below). | Item | Decision |
- [ ] Choose primary content plane for stage 1 + migration path. |------|----------|
- [ ] Choose asset strategy (in-kontextual vs extract vs folder-only). | Content plane start | **A** thin dir + git |
- [ ] File ADR-0003 (page model + SoR) and ADR-0004 (content plane). | Upgrades | → shard-wiki → kontextual (supported) |
- [ ] Update `docs/capability/model-v0.yaml` feature wording if PageOps replaces Forgejo-centric features. | asset-store | **Later** |
| Authz ownership | **NetKingdom consolidation** (avoid parallel PolicyGateway fiefdom) |
| Structure UX | Outline **explode/implode**; **live** default; pin exception |
### Scorecard (1–5, higher better) Remaining workshop work:
| Criterion | A thin store | B shard-wiki | C kontextual | - [ ] File ADR-0003 / ADR-0004 reflecting D1–D4.
|-----------|:------------:|:------------:|:------------:| - [ ] Sketch export/import round-trip notes for B and C upgrades (feasibility only).
| Markdown export fidelity | | | | - [ ] Explode/implode UX prototype on thin tree (Spike 2 + markitect).
| Stage-1 speed | | | |
| Structure tax (inverse) | | | |
| Copy/transfer naturalness | | | |
| Visual/blob readiness | | | |
| NetKingdom/authz fit | | | |
| Multi-shard / federation later | | | |
| Multi-format / ECM later | | | |
| Railiance operability | | | |
| Aligns with fleet layers | | | |
| **Total** | | | |
--- ---

16
docs/architecture/stale-derived-content.md
View file

@ -118,20 +118,22 @@ Same for abstractor and visual (visual compare: two images or image vs placehold
Two legitimate modes (both needed): Two legitimate modes (both needed):
### A. Live resolve (dynamic) ### A. Live resolve (dynamic) — **product default**
```markdown ```markdown
<!-- mkt:include path="src.md" selector="sections[heading=API]" --> <!-- mkt:include path="src.md" selector="sections[heading=API]" -->
``` ```
At render/export, markitect resolves from **current** `src.md`. At render/export, markitect resolves from **current** `src.md`
“Stale” is less about the marker and more about **viewer cache**. (**spreadsheet-like**: formula results stay up to date).
Still useful: badge if **last rendered snapshot** ≠ current resolve hash
(for offline cards that show a cached excerpt).
### B. Pinned / materialised include (snapshot in host page) “Stale” for pure live includes is mostly **viewer/cache** (optional badge if
a cached card excerpt lags live resolve). No replace/keep needed unless the
host cached a display snapshot.
For “user owns a frozen copy but can refresh”: ### B. Pinned / materialised include (snapshot in host page) — **exception**
For “freeze this excerpt / paste values” (explicit pin):
```markdown ```markdown
<!-- mkt:derived id="api-excerpt" <!-- mkt:derived id="api-excerpt"

8
docs/architecture/transclusion-and-chunks.md
View file

@ -172,10 +172,12 @@ then pin/freeze excerpts when “my version vs live source” matters.
| Mode | Behavior | | Mode | Behavior |
|------|----------| |------|----------|
| Live `mkt:include` | Always resolve current source at render | | **Live** `mkt:include` (**default**) | Always resolve current source — spreadsheet-like |
| Pinned `mkt:derived` (proposed) | Store snapshot; badge when source/inputs change; user generates alternative and chooses replace or keep | | **Pinned** `mkt:derived` (proposed) | Explicit freeze; badge when inputs change; alternative → replace \| keep |
Both are valid; co-creation often wants **pin + explicit refresh**. **Product default is live.** Pin only when the user freezes a value.
Outline flexibility uses **explode / implode** into connected docs with live
links, not a priori chunk tables.
--- ---

15
docs/capability/model-v0.yaml
View file

@ -121,9 +121,20 @@ capabilities:
title: Stale badge with generate alternative then replace or keep title: Stale badge with generate alternative then replace or keep
status: todo status: todo
notes: "docs/architecture/stale-derived-content.md; markitect derived slots" notes: "docs/architecture/stale-derived-content.md; markitect derived slots"
- id: feat.derived-include-pin - id: feat.include-live-default
title: Pinned include/pipeline snapshots with same stale/replace grammar title: Live includes by default (spreadsheet-like up-to-date resolve)
status: todo status: todo
- id: feat.derived-include-pin
title: Optional pin; stale badge with generate alternative then replace or keep
status: todo
- id: feat.outline-explode-implode
title: Outline-editor explode into connected docs and implode back
status: todo
notes: "markitect explode/implode; ArchitectureBlueprint D4"
- id: feat.content-plane-thin-git
title: Content SoR as directory + markdown files in git
status: todo
notes: "Upgrades to shard-wiki then kontextual supported later"
- id: feat.content-fail-closed - id: feat.content-fail-closed
title: Fail closed on missing binding/fetch title: Fail closed on missing binding/fetch
status: shipped status: shipped