diff --git a/docs/architecture/ArchitectureBlueprint.md b/docs/architecture/ArchitectureBlueprint.md index 6b74c12..c70c363 100644 --- a/docs/architecture/ArchitectureBlueprint.md +++ b/docs/architecture/ArchitectureBlueprint.md @@ -2,31 +2,21 @@ | Field | Value | |-------|--------| -| Status | **draft for discussion** (revised 2026-08-13) | +| Status | **draft — decisions recorded 2026-08-13** | | Product | coulomb.social rebuild (`coulomb-social`) | -| Related | stage-1 cut, capability maps, substrate exploration, authoring, stale/derived | -| Non-goals | Final store vendor lock-in; full UI chrome; implementing markitect features in this doc | +| Related | stage-1 cut, capability maps, authoring, stale/derived, upgrade path | +| 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 | -|-------|--------| -| 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. +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. --- @@ -36,62 +26,66 @@ Deliver a co-creation product where: 1. **Identity** (users, groups, tenants) is **NetKingdom** — 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. -5. **markitect-tool** makes markdown an efficient structured substrate (lib/CLI/API) — **not** the product host. -6. **coulomb** owns co-creation UI (cards, spaces, copy/transfer, authoring UX) and product verbs. -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. +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, outline-oriented editing, copy/transfer). +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 | # | Rule | |---|------| -| R1 | Markdown (frontmatter + body + backmatter) + assets are the **exportable SoR** for content. | -| R2 | App DB holds **projections and app linkage only** for content; disposable for bodies. | +| R1 | Markdown (frontmatter + body + backmatter) + assets under a **directory tree** are the **exportable SoR**. | +| R2 | App DB holds **projections and app linkage only**; disposable for content bodies. | | 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. | -| R6 | **markitect-tool** is the markdown structure dependency (parse, validate, query, include, later derived slots). | -| R7 | Content plane (shard-wiki / kontextual / thin store) sits behind a **narrow PageOps** interface. | +| R6 | **markitect-tool** is the markdown structure dependency. | +| 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. | -| R9 | **Pages first** — do not model documents as a priori chunk assemblies; use address/transclude/promote. | -| R10 | Derived content (projections, pinned includes, pipelines, AI) uses **stale badge → alternative → replace\|keep** and **lock**; no silent overwrite of locked/user content. | +| R9 | **Pages first** — address / live-transclude / explode-implode / promote; not a priori chunk storage. | +| 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 ```text ┌──────────────────────────┐ │ NetKingdom │ - │ OIDC, groups, tenants │ + │ OIDC · groups · tenants│ + │ (authz consolidation →)│ └────────────┬─────────────┘ │ principal ▼ ┌─────────────────────────────────────────────────────────────┐ │ coulomb.social (product) │ -│ • Card UI, spaces chrome, dual authoring flows │ -│ • Session / Member / SpaceMembership │ -│ • PageOps + projection UX (lazy / stale / lock) │ +│ • Cards, spaces, dual authoring, outline explode/implode │ +│ • PageOps; live resolve; pin when asked │ │ • Railiance deploy │ └───────────────┬─────────────────────────────┬───────────────┘ - │ projections │ content ops + │ cache │ PageOps ▼ ▼ ┌───────────────┐ ┌───────────────────────────┐ - │ App DB cache │ │ Content plane (adapter) │ - │ (Postgres) │ │ A thin folder/git │ - └───────────────┘ │ B shard-wiki (thin) │ - │ C kontextual-engine │ + │ Postgres │ │ Content plane │ + │ projections │ │ ★ A thin dir + git │ + └───────────────┘ │ (default / stage-1) │ + │ ↗ B shard-wiki upgrade │ + │ ↗ C kontextual upgrade │ └─────────────┬─────────────┘ - │ structure - ▼ - ┌───────────────────────────┐ + │ + ┌─────────────▼─────────────┐ │ markitect-tool │ - │ parse, FM, query, include │ - │ derived/stale (proposed) │ + │ structure · include LIVE │ + │ explode/implode · query │ + │ pin/derived (proposed) │ └─────────────┬─────────────┘ ▼ ┌───────────────────────────┐ - │ Asset bytes (blobs) │ - │ content-addressed │ + │ Assets (files next to md) │ + │ later: shared asset-store │ └───────────────────────────┘ ``` @@ -99,188 +93,210 @@ Deliver a co-creation product where: | Op | Meaning | |----|---------| -| `list_pages(space)` | Card projections | -| `get_page(id)` | Full markdown + resolved visual; optional include resolve | -| `put_page(...)` | Create/update attributes + body | -| `archive_page` | Soft-delete / lifecycle | -| `copy_page` | Independent duplicate (rewrite includes as needed) | -| `transfer_page` | Re-home to another space | -| `put_visual` / `get_asset` | Binary visual/attachment | -| `project_field` / `regenerate` / `lock` | Lazy & stale projection actions | -| `derived_refresh` | Stale include/pipeline: alternative → replace\|keep (when markitect supports) | +| `list_pages` / `get_page` / `put_page` / `archive_page` | CRUD | +| `copy_page` / `transfer_page` | Duplicate / re-home | +| `explode_page` / `implode_pages` | Outline-style split/join (markitect) | +| `resolve_view` | Live includes/derived for display (default) | +| `pin_slot` / `unpin` / `refresh_pinned` | Freeze snapshot; stale → alternative → replace\|keep | +| `project_field` / `regenerate` / `lock` | Title/abstractor/visual lifecycle | +| `put_visual` / `get_asset` | Binary next to tree (later asset-store) | -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) | Concept | Representation | |---------|----------------| -| **Page** | Markdown: frontmatter (title, abstractor, visual, space, projections lifecycle, …) + body + backmatter | -| **Space** | Container; may be `type: space` page or container id in frontmatter | -| **Visual** | Asset ref → blob store | -| **Card** | UI only: visual + title + abstractor + actions (+ stale badges) | -| **Region / “chunk”** | Addressable unit of a page (heading, `mkt:region`, selector) — **not** a required storage type | -| **Transclusion** | Live `mkt:include` and/or pinned `mkt:derived` snapshot (proposed) | +| **Page** | One markdown file (or connected set after explode) | +| **Space** | Directory / container + metadata page | +| **Tree** | Git-secured directory layout | +| **Card** | UI projection (title, abstractor, visual, actions, stale) | +| **Outline** | Headings / exploded connected docs — **not** Bubble chunk rows | +| **Live include** | `mkt:include` resolves current source (default) | +| **Pinned derived** | Optional frozen snapshot; explicit refresh | | **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 -Write fluently in a page - → address regions when needed - → transclude / extract / promote - → materialize a new page only when reuse earns independence +spaces// + pages/.md + assets/… +# 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 | -| **Pros** | Fastest S1; trivial export; low structure tax | -| **Cons** | Copy/transfer/versioning are app work; federation later costs more | -| **When** | Velocity first; plane maturity unclear | +| **Why** | Simplest SoR; user data is files; matches “secured in git” | +| **coulomb role** | PageOps over filesystem/git; DB indexes cards | +| **markitect role** | Parse, live include, explode/implode, validate | -### 5.2 Option B — shard-wiki (thin slice) +### 5.2 Upgrade B — shard-wiki -| | | -|--|--| -| **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 | +When multi-shard wiki behavior, overlays, or federation become product-relevant: -### 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. -| | | -|--|--| -| **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.3 Upgrade C — kontextual-engine -### 5.4 Evolution (not exclusive forever) +When asset identity, scale, rich multi-format media, audit/lineage, or ECM-class governance dominate: -```text -PageOps → A or thin B/C now - → folder/git shard can become shard-wiki - → assets can move to kontextual / asset-store - → markitect-tool always structure layer -``` +- Supported **migration** of the information base into kontextual assets/blobs. +- Markdown remains the portable authoring/export form where applicable. +- **Not** required for stage-1. -**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 | -|--------|------| -| 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 | +## 6. Assets (deferred extract) -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 ```text Browser → NetKingdom OIDC → coulomb session - ├─ product authz: tenant_id, SpaceMembership - └─ content plane: Actor(external_ref=iss|sub, groups=…) - PolicyGateway → flex-auth (preferred) + ├─ product: tenant_id, SpaceMembership (and future NK groups) + └─ long-term: NetKingdom-consolidated authz (flex-auth / NK) + 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) | Component | Deploy | |-----------|--------| | coulomb-social | Existing chart; `app.coulomb.social` | -| Content plane | In-process, sidecar, or platform service | -| Asset bytes | PVC and/or S3; secrets via env-secret pattern | +| Content tree | Volume or git-backed storage accessible to the app; **git** is SoR discipline | +| Assets | Beside markdown until asset-store | | 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) -- 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 +**Aspire early (structure UX):** -**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 | ADR | Topic | |-----|--------| | ADR-0001 | NetKingdom identity (**done**) | -| ADR-0002 | Forgejo binding — **demote** to one adapter/export shape | -| **ADR-0003** | Page-centric model + SoR + DB cache + page-first/transclusion | -| **ADR-0004** | Content-plane choice + PageOps | -| **ADR-0005** | Asset-store extraction (if/when) | -| **ADR-0006** | Authoring modes + projections + stale/derived (or fold into 0003) | +| ADR-0002 | Forgejo slice → **one optional git remote / export**, not unique SoR | +| **ADR-0003** | Page model + dir+git SoR + page-first + live default + authoring/stale | +| **ADR-0004** | PageOps + **thin plane** + **upgrade path** B/C | +| **ADR-0005** | asset-store extraction (**later**) | +| — | 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)**. -Add when scheduling: dual-authoring smoke, stale projection compare UX, include pin (after markitect). +With D1–D4, prioritize: -## 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**? -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? +Defer deep shard-wiki/kontextual spikes except **export/import round-trip sketches** that prove upgrade feasibility. -## 13. Working recommendation (principles frozen; plane open) +Full list remains in `spike-checklist.md` (update scorecard: A = chosen start). -| Layer | Recommendation | -|-------|----------------| -| Product UI | coulomb cards + spaces + dual authoring | -| Markdown structure | markitect-tool (includes + future derived slots) | -| Identity / deploy | NetKingdom / Railiance | -| Content plane | Spike A+B+C; choose with export fidelity as hard constraint | -| SoR | Markdown export always works; engines add IDs/lineage without trapping content | -| Assets | kontextual blobs now; extract later if shared | -| Chunks | Transclusion/extract, not a priori graph | -| Derived/stale | Badge → alternative → replace\|keep + lock | +## 12. Closed discussion prompts + +| Prompt | Resolution | +|--------|------------| +| A vs B vs C for start | **A**; B/C = supported upgrades | +| asset-store now? | **Later** | +| PolicyGateway owner | **Consolidate under NetKingdom**; don’t fork ownership | +| Chunk UX | **Outline editor + explode/implode**, not chunk tables | +| Live vs pin default | **Live**; pin is explicit | + +--- + +## 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 | --- @@ -301,7 +317,7 @@ Add when scheduling: dual-authoring smoke, stale projection compare UX, include ### fleet -- kontextual: architecture-blueprint, asset-registry, blob-storage, markitect reuse boundary -- shard-wiki: INTENT, SCOPE -- markitect-tool: transform-compose-include, content-references, cache-incremental, **proposed-stale-derived-and-include-pinning.md** -- markitect-main: successor-gap-assessment (legacy) +- markitect-tool: transform-compose-include, explode-implode, content-references, **proposed-stale-derived-and-include-pinning.md** +- shard-wiki: INTENT (Coulomb as consumer; upgrade target) +- kontextual: blob-storage, asset-registry (upgrade + later asset-store seed) +- markitect-main: successor-gap (legacy only) diff --git a/docs/architecture/spike-checklist.md b/docs/architecture/spike-checklist.md index 2308414..6e5b48b 100644 --- a/docs/architecture/spike-checklist.md +++ b/docs/architecture/spike-checklist.md @@ -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 -**Depends on:** Spikes 1–6 results +**Recorded in ArchitectureBlueprint §0 (D1–D4):** -- [ ] Fill scorecard (below). -- [ ] Choose primary content plane for stage 1 + migration path. -- [ ] Choose asset strategy (in-kontextual vs extract vs folder-only). -- [ ] File ADR-0003 (page model + SoR) and ADR-0004 (content plane). -- [ ] Update `docs/capability/model-v0.yaml` feature wording if PageOps replaces Forgejo-centric features. +| Item | Decision | +|------|----------| +| Content plane start | **A** thin dir + git | +| Upgrades | → shard-wiki → kontextual (supported) | +| 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 | -|-----------|:------------:|:------------:|:------------:| -| Markdown export fidelity | | | | -| 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** | | | | +- [ ] File ADR-0003 / ADR-0004 reflecting D1–D4. +- [ ] Sketch export/import round-trip notes for B and C upgrades (feasibility only). +- [ ] Explode/implode UX prototype on thin tree (Spike 2 + markitect). --- diff --git a/docs/architecture/stale-derived-content.md b/docs/architecture/stale-derived-content.md index 190aa58..83f74ee 100644 --- a/docs/architecture/stale-derived-content.md +++ b/docs/architecture/stale-derived-content.md @@ -118,20 +118,22 @@ Same for abstractor and visual (visual compare: two images or image vs placehold Two legitimate modes (both needed): -### A. Live resolve (dynamic) +### A. Live resolve (dynamic) — **product default** ```markdown ``` -At render/export, markitect resolves from **current** `src.md`. -“Stale” is less about the marker and more about **viewer cache**. -Still useful: badge if **last rendered snapshot** ≠ current resolve hash -(for offline cards that show a cached excerpt). +At render/export, markitect resolves from **current** `src.md` +(**spreadsheet-like**: formula results stay up to date). -### 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