pdurlej/platform
1
1
Fork 0
Code Issues 44 Pull requests 1 Projects Releases Packages Wiki Activity Actions

feat(phase02): karakeep family — wave 2 audit + sidecar consolidation #34

Merged
pdurlej merged 1 commit from claude/orders/phase-02-karakeep-family into main 2026-05-03 02:06:48 +02:00
Conversation 0 Commits 1 Files changed 7 +285 -124
pdurlej commented 2026-05-03 01:35:31 +02:00
Owner
Copy link

Summary

Phase 02 wave 2 manifests for karakeep family. Operator decision (2026-05-03, audit findings option c): main + meilisearch as separate modules (both stateful), chrome inline (stateless, no separate module). No literówka in karakeep-meilisearch — Meilisearch is the correct French startup product name (operator self-corrected after karakeep issue #543).

Closes wave 2: PR #32 (uptime-kuma) + #33 (umami) merged earlier; this completes the wave.

Changes

modules/karakeep/module.yaml (main)

Schema v2 fields:

  • image_observed: ghcr.io/karakeep-app/karakeep:0.30.0@sha256:862c3f63…, image_digest_pinned_in_compose: false, image_audit_ts: 2026-05-03T07:30:00Z, image_build: registry, statefulness: sidecar-bound (own /data + meilisearch sidecar index)

Drift fixes:

  • dependencies.upstream: [traefik, postgres, karakeep-meilisearch] → [traefik, karakeep-meilisearch, karakeep-chrome] — karakeep does NOT use postgres (uses local SQLite at /data); chrome added as inline-sidecar dependency
  • Added dependencies.data_stores: home-platform_karakeep_data (critical)

intent expanded with user_facing_outcome (covers karakeep + 2 sidecars in one narrative) + acceptance_criteria (includes both sidecar healthchecks).

acknowledged_risks × 2:

  • container-runs-as-root — mitigated by signups disabled (DISABLE_SIGNUPS=true + NEXT_PUBLIC_DISABLE_SIGNUPS=true), so no untrusted user input
  • chrome-sidecar-no-sandbox — alpine-chrome runs with --no-sandbox flag; mitigated because chrome only loads operator-saved URLs (input set is operator-trusted)

modules/karakeep-meilisearch/module.yaml

Schema v2 fields:

  • image_observed: getmeili/meilisearch:v1.13.3@sha256:35435ac7…, image_digest_pinned_in_compose: false, image_audit_ts: 2026-05-03T07:30:00Z, image_build: registry, statefulness: stateful

Drift fix:

  • data_stores.volume: home-platform-karakeep-meilisearch-data (dashes — wrong) → home-platform_karakeep_meilisearch_data (underscores — actual docker volume name, project_volname pattern)

acknowledged_risks × 2:

  • container-runs-as-root — mitigated by internal-only exposure + master-key gating + rebuildable index
  • master-key-in-plaintext-stack-env — mitigated by internal-only exposure + RS2000 stack.env root-only readable; karakeep listed in INFISICAL_EXPORT_PATHS for migration

modules/karakeep-chrome/ — REMOVED

Per option (c): chrome inline because stateless. Removed module.yaml + runbook.md. Chrome documented in karakeep main runbook under "Inline sidecars" section (image, user, networks, command flags, acknowledged_risk reference, recovery procedure).

modules/INDEX.yaml

Removed karakeep-chrome entry. karakeep + karakeep-meilisearch remain.

Runbooks (both)

Follow n8n-worker canary-validated pattern (yq-from-manifest digest, compose/apps/ cwd, platformctl apply <plan_file> --approved <sha> CLI). karakeep adds "Inline sidecars" section. karakeep-meilisearch documents index-rebuild fast-path (drop volume, let karakeep main re-index from /data).

Verification

  • jsonschema.validate passes for both module.yaml files
  • Token budgets: karakeep 991/1500, karakeep-meilisearch 864/1500
  • image_observed digests match docker inspect for both containers (2026-05-03)
  • INDEX.yaml parses YAML cleanly, 80 modules listed (was 81), karakeep-chrome entry absent, karakeep + karakeep-meilisearch present
  • No modules/karakeep-chrome/ dir on disk
  • Recovery commands use canary-validated patterns from PR #29

Test plan

  • Schema validation
  • Token count
  • Manual readback: chrome sidecar inline section is sufficient (no orphaned references to karakeep-chrome module elsewhere in repo)
  • Canary review (3+3 ensemble) — note: 7-file PR, larger surface area than #32/#33; reviewers should verify karakeep-chrome removal is clean
## Summary Phase 02 wave 2 manifests for karakeep family. Operator decision (2026-05-03, audit findings option **c**): main + meilisearch as separate modules (both stateful), chrome inline (stateless, no separate module). No literówka in karakeep-meilisearch — Meilisearch is the correct French startup product name (operator self-corrected after [karakeep issue #543](https://github.com/karakeep-app/karakeep/issues/543)). Closes wave 2: PR #32 (uptime-kuma) + #33 (umami) merged earlier; this completes the wave. ## Changes ### `modules/karakeep/module.yaml` (main) Schema v2 fields: - `image_observed: ghcr.io/karakeep-app/karakeep:0.30.0@sha256:862c3f63…`, `image_digest_pinned_in_compose: false`, `image_audit_ts: 2026-05-03T07:30:00Z`, `image_build: registry`, `statefulness: sidecar-bound` (own `/data` + meilisearch sidecar index) Drift fixes: - `dependencies.upstream: [traefik, postgres, karakeep-meilisearch]` → `[traefik, karakeep-meilisearch, karakeep-chrome]` — karakeep does NOT use postgres (uses local SQLite at `/data`); chrome added as inline-sidecar dependency - Added `dependencies.data_stores: home-platform_karakeep_data` (critical) `intent` expanded with `user_facing_outcome` (covers karakeep + 2 sidecars in one narrative) + `acceptance_criteria` (includes both sidecar healthchecks). `acknowledged_risks` × 2: - `container-runs-as-root` — mitigated by signups disabled (`DISABLE_SIGNUPS=true` + `NEXT_PUBLIC_DISABLE_SIGNUPS=true`), so no untrusted user input - `chrome-sidecar-no-sandbox` — alpine-chrome runs with `--no-sandbox` flag; mitigated because chrome only loads operator-saved URLs (input set is operator-trusted) ### `modules/karakeep-meilisearch/module.yaml` Schema v2 fields: - `image_observed: getmeili/meilisearch:v1.13.3@sha256:35435ac7…`, `image_digest_pinned_in_compose: false`, `image_audit_ts: 2026-05-03T07:30:00Z`, `image_build: registry`, `statefulness: stateful` Drift fix: - `data_stores.volume: home-platform-karakeep-meilisearch-data` (dashes — wrong) → `home-platform_karakeep_meilisearch_data` (underscores — actual docker volume name, `project_volname` pattern) `acknowledged_risks` × 2: - `container-runs-as-root` — mitigated by internal-only exposure + master-key gating + rebuildable index - `master-key-in-plaintext-stack-env` — mitigated by internal-only exposure + RS2000 `stack.env` root-only readable; karakeep listed in `INFISICAL_EXPORT_PATHS` for migration ### `modules/karakeep-chrome/` — REMOVED Per option (c): chrome inline because stateless. Removed `module.yaml` + `runbook.md`. Chrome documented in karakeep main runbook under "Inline sidecars" section (image, user, networks, command flags, acknowledged_risk reference, recovery procedure). ### `modules/INDEX.yaml` Removed `karakeep-chrome` entry. `karakeep` + `karakeep-meilisearch` remain. ### Runbooks (both) Follow n8n-worker canary-validated pattern (yq-from-manifest digest, `compose/apps/` cwd, `platformctl apply <plan_file> --approved <sha>` CLI). karakeep adds "Inline sidecars" section. karakeep-meilisearch documents index-rebuild fast-path (drop volume, let karakeep main re-index from `/data`). ## Verification - [x] `jsonschema.validate` passes for both `module.yaml` files - [x] Token budgets: karakeep 991/1500, karakeep-meilisearch 864/1500 - [x] `image_observed` digests match `docker inspect` for both containers (2026-05-03) - [x] `INDEX.yaml` parses YAML cleanly, 80 modules listed (was 81), `karakeep-chrome` entry absent, `karakeep` + `karakeep-meilisearch` present - [x] No `modules/karakeep-chrome/` dir on disk - [x] Recovery commands use canary-validated patterns from PR #29 ## Test plan - [ ] Schema validation - [ ] Token count - [ ] Manual readback: chrome sidecar inline section is sufficient (no orphaned references to `karakeep-chrome` module elsewhere in repo) - [ ] Canary review (3+3 ensemble) — note: 7-file PR, larger surface area than #32/#33; reviewers should verify `karakeep-chrome` removal is clean 
Phase 02 wave 2 manifests for karakeep family. Operator decision (2026-05-03,
audit findings option **c**): main + meilisearch as separate modules
(both stateful), chrome inline (stateless, no separate module). No
literowka in karakeep-meilisearch — Meilisearch is the correct French
startup product name (operator self-corrected).

## modules/karakeep/module.yaml (main)

Schema v2 fields per PR #29 pattern:
- image_observed: ghcr.io/karakeep-app/karakeep:0.30.0@sha256:862c3f63…
- image_digest_pinned_in_compose: false (env carries tag only)
- image_audit_ts: 2026-05-03T07:30:00Z
- image_build: registry
- statefulness: sidecar-bound (own /data + meilisearch sidecar index)

Drift fixes:
- dependencies.upstream: [traefik, postgres, karakeep-meilisearch] →
  [traefik, karakeep-meilisearch, karakeep-chrome]
  (karakeep does NOT use postgres; uses local SQLite at /data; chrome
  added as inline-sidecar dependency)
- Added dependencies.data_stores: home-platform_karakeep_data (critical)

intent expanded:
- user_facing_outcome describes karakeep + 2 sidecars in one narrative
- acceptance_criteria includes both sidecar healthchecks

acknowledged_risks (2):
- container-runs-as-root: image runs as root; mitigated by signups
  disabled (DISABLE_SIGNUPS=true + NEXT_PUBLIC_DISABLE_SIGNUPS=true)
  so no untrusted user input
- chrome-sidecar-no-sandbox: alpine-chrome runs with --no-sandbox
  flag; mitigated by chrome only loading operator-saved URLs (input
  set is operator-trusted)

## modules/karakeep-meilisearch/module.yaml

Schema v2 fields:
- image_observed: getmeili/meilisearch:v1.13.3@sha256:35435ac7…
- image_digest_pinned_in_compose: false
- image_audit_ts: 2026-05-03T07:30:00Z
- image_build: registry
- statefulness: stateful (search index in /meili_data)

Drift fix:
- data_stores.volume: home-platform-karakeep-meilisearch-data
  (dashes — wrong) → home-platform_karakeep_meilisearch_data
  (underscores — actual docker volume name, project_volname pattern)

acknowledged_risks (2):
- container-runs-as-root: meilisearch runs as root; mitigated by
  internal-only exposure + master-key gating + rebuildable index
- master-key-in-plaintext-stack-env: KARAKEEP_MEILI_MASTER_KEY in
  plaintext stack.env; mitigated by internal-only exposure + RS2000
  stack.env root-only readable; karakeep listed in
  INFISICAL_EXPORT_PATHS for migration

## modules/karakeep-chrome/ — REMOVED

Per option (c): chrome inline because stateless. Removed module.yaml +
runbook.md. Chrome documented in karakeep main runbook under "Inline
sidecars" section with image, user, networks, command flags, and
acknowledged_risk reference.

## modules/INDEX.yaml

Removed `karakeep-chrome` entry. karakeep + karakeep-meilisearch
remain.

## Runbooks (both)

Follow n8n-worker canary-validated pattern:
- yq-from-manifest digest pattern
- compose_file-relative cwd (/opt/.../compose/apps/)
- platformctl apply <plan_file> --approved <sha> CLI signature
- Live state audit table + Import phase plan + Release readiness
- karakeep adds explicit "Inline sidecars" section documenting chrome
  + meilisearch handoffs
- karakeep-meilisearch documents index-rebuild fast-path (drop volume,
  let karakeep main re-index from /data)

Schema: both validate OK. Token budgets: karakeep 991/1500,
karakeep-meilisearch 864/1500.
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels   
W6d-automerge-calibration

   
agent/claude-code
Vistula actor: Claude Code.

  
agent/codex
Vistula actor: Codex.

  
agent/hermes
Vistula actor: Hermes Upstream.

  
agent/iskra
Vistula actor: Iskra.

  
agent/ollama
Vistula actor: Ollama or compatible model.

  
agent/patchwarden
Vistula actor: Patchwarden.

  
automerge-candidate
Candidate for narrow W6d autonomous merge readiness pilot

  
class/security-sensitive
Security-sensitive class of service: smallest coherent PRs and full canary

  
cutover-gate
blocks production declare / final RS2000 replacement

  
dependency/blocked
Vistula dependency state: blocked.

  
dependency/blocks-others
Vistula dependency state: blocks other work.

  
dependency/cross-repo
Vistula dependency scope: cross-repository.

  
dependency/needs-confirmation
Vistula dependency state: needs confirmation.

  
domain:agents
Agent identity, delegation, subagents, routing, or workflows.

  
domain:ci
CI, checks, Actions, runners, or release automation.

  
domain:docs
Documentation, packets, practices, or source-of-truth text.

  
domain:forgejo
Forgejo issues, PRs, labels, repo settings, or identity.

  
domain:infra
Infrastructure, storage, backup, DNS, network, or host substrate.

  
domain:memory
Memory, recall, write gates, salience, or Honcho-adjacent behavior.

  
domain:runtime
Runtime services, deploys, daemons, timers, or live behavior.

  
domain:signal
Signal UX, delivery, context, or outbound behavior.

  
domain:ux
Product UX, operator experience, or conversation ergonomics.

  
flow/architecture
Vistula lifecycle: architecture phase in progress.

  
flow/blocked
Vistula lifecycle: blocked on dependency or decision.

  
flow/deployed
Vistula lifecycle: deployed to runtime where applicable.

  
flow/done
Vistula lifecycle: work merged or otherwise done.

  
flow/implementation
Vistula lifecycle: implementation phase in progress.

  
flow/intake
Vistula lifecycle: incoming signal not refined yet.

  
flow/maintained
Vistula lifecycle: maintained/steady state.

  
flow/observed
Vistula lifecycle: observed after delivery.

  
flow/ready
Vistula lifecycle: ready for architecture or implementation.

  
flow/refining
Vistula lifecycle: Hermes/spec refinement in progress.

  
flow/retired
Vistula lifecycle: retired or intentionally closed.

  
flow/review
Vistula lifecycle: review phase in progress.

  
iterating
Orchestrator/Codex actively amending in response to review — operator can ignore until resolved

  
judge/codex-candidate
Candidate for Codex implementation.

  
judge/hermes-candidate
Candidate for Hermes discovery/research.

  
judge/low-confidence
Judgment confidence is low.

  
judge/needs-refinement
Needs clearer evidence or scope.

  
judge/operator-needed
Needs Piotr decision or input.

  
judge/p0
Urgent, operator attention or unblock now.

  
judge/p1
High value, schedule soon.

  
judge/p2
Useful, normal queue.

  
judge/p3
Low priority, keep but do not chase.

  
judge/park
Parked from current attention.

  
judge/patchwarden-candidate
Needs Patchwarden merge-safety attention.

  
judge/stale-priority
Existing priority judgment appears stale.

  
kind/adr
Vistula work kind: architecture decision record.

  
kind/bug
Vistula work kind: bug fix.

  
kind/chore
Vistula work kind: chore.

  
kind/feature
Vistula work kind: feature.

  
kind/infra
Vistula work kind: infrastructure.

  
kind/ops
Vistula work kind: operations.

  
kind/refactor
Vistula work kind: refactor.

  
kind/research
Vistula work kind: research/discovery.

  
large-impact
Per charter §3 review-by-impact: large impact (≥300 LOC OR new module OR identity/secret change OR architectural pivot) — Oracle pre-review recommended

  
merge/auto
Vistula merge mode: automated merge.

  
merge/manual
Vistula merge mode: manual merge.

  
merge/manual-dependency-conflict
Manual merge reason: dependency conflict.

  
merge/manual-failing-tests
Manual merge reason: failing tests.

  
merge/manual-merge-conflict
Manual merge reason: merge conflict.

  
merge/manual-missing-review
Manual merge reason: missing review.

  
merge/manual-operator-preference
Manual merge reason: operator preference.

  
merge/manual-red-zone
Manual merge reason: red-zone risk.

  
merge/manual-security-sensitive
Manual merge reason: security-sensitive work.

  
merge/manual-unclear-scope
Manual merge reason: unclear scope.

  
merge/manual-unknown
Manual merge reason: unknown.

  
meta
meta-decomposition issue; first agent decomposes into atomic children

  
mode:operator-only
Apply step requires explicit operator approval.

  
mode:patchwarden-iskra-approved
Work eligible for Patchwarden/Iskra approval inside repo policy.

  
mode:safe-auto
Low-risk work eligible for lightweight autonomous handling.

  
needs-operator-decision
PR is blocked on operator yes/no decision — fresh-Claude/Codex won't make this call alone

  
needs-triage
decomposing agent has open questions / unknowns

  
not-ready
reviewed but blocked on a precondition

  
observed/erroring
Vistula observation: erroring.

  
observed/needs-followup
Vistula observation: needs follow-up.

  
observed/pending
Vistula observation: pending.

  
observed/retire-candidate
Vistula observation: retire candidate.

  
observed/unused
Vistula observation: unused.

  
observed/used
Vistula observation: used.

  
operator-emotional
operator-emotional importance (Iskra memory etc.)

  
owner-attention
owner must decide; blocks default path

  
phase/02
Phase 02 cataloging

  
phase/03
Phase 03 control plane (platformctl)

  
priority:p0
Immediate safety, uptime, data, or operator-blocking issue.

  
priority:p1
Important active work; should be pulled soon.

  
priority:p2
Useful normal-priority work.

  
priority:p3
Opportunistic cleanup, research, or backlog work.

  
proposed
auto-generated by meta-decomposition; awaiting human review

  
ready-for-agent
reviewed and pickable; agents may claim per cookbook

  
ready-for-operator
PR is ready for operator review/merge — orchestrator finished its part

  
recovery
disaster recovery / restore semantics relevant

  
review:claude-reviewed
Reviewed by Claude-family agent.

  
review:codex-reviewed
Reviewed by Codex-family agent.

  
review:dziadek-reviewed
Reviewed by Dziadek pinch-point reviewer.

  
review:needs-human
Needs human review before merge or apply.

  
risk/exposure
incorrectly public/private/tailnet/auth/routed

  
risk/process
workflow/review/orchestration may produce bad outcomes

  
risk/product
work may have lost owner/user value

  
risk/runtime
platform may not run, recover, validate, behave reproducibly

  
safety:external-write
May write to external systems, users, rooms, repos, or services.

  
safety:no-prod-mutation
Must not mutate production or live external state.

  
safety:prod-impact
May affect production/runtime behavior.

  
safety:secret-touch
Touches secrets, credentials, auth, or secret-adjacent config.

  
size/large
Vistula size: large.

  
size/medium
Vistula size: medium.

  
size/small
Vistula size: small.

  
size/tiny
Vistula size: tiny.

  
size/unknown
Vistula size: not classified yet.

  
source/adr
Vistula source: ADR.

  
source/agent-generated
Vistula source: agent generated.

  
source/manual
Vistula source: manual entry.

  
source/operator-chat
Vistula source: operator chat.

  
source/voice-note
Vistula source: voice note.

  
status:blocked
Blocked by missing dependency, evidence, access, or operator decision.

  
status:codex-ready
Ready for a Codex implementation pass.

  
status:merged:pending-evidence
Merged but waiting for live or artifact evidence before closure.

  
status:needs-evidence
Needs proof, logs, tests, or operator-visible evidence.

  
status:operator-needed
Requires explicit operator input before safe progress.

  
status:parked
Intentionally deferred; not active campaign work.

  
tier/full
Full review tier per ADR-0007

  
tier/lite
Lite review tier per ADR-0007

  
tier/stacked
Stacked PR (base != main) escape hatch per ADR-0017. Requires consolidator-PR plan in PR body.

  
tier:0-platform-substrate
Data, secrets, backup, storage, or critical platform substrate.

  
tier:1-iskra-value-layer
Iskra/OpenClaw behavior, memory, runtime, or value-layer work.

  
tier:2-tools-products-modules
Tools, products, modules, experiments, and lower-blast-radius work.

  
type:bug
Incorrect behavior or regression.

  
type:chore
Maintenance, cleanup, metadata, or operational task.

  
type:docs
Documentation-only work.

  
type:feat
New capability or product behavior.

  
type:policy
Governance, protocol, boundary, or decision-contract change.

  
type:research
Investigation, spike, or evidence-gathering task.

No labels
W6d-automerge-calibration
agent/claude-code
agent/codex
agent/hermes
agent/iskra
agent/ollama
agent/patchwarden
automerge-candidate
class/security-sensitive
cutover-gate
dependency/blocked
dependency/blocks-others
dependency/cross-repo
dependency/needs-confirmation
domain:agents
domain:ci
domain:docs
domain:forgejo
domain:infra
domain:memory
domain:runtime
domain:signal
domain:ux
flow/architecture
flow/blocked
flow/deployed
flow/done
flow/implementation
flow/intake
flow/maintained
flow/observed
flow/ready
flow/refining
flow/retired
flow/review
iterating
judge/codex-candidate
judge/hermes-candidate
judge/low-confidence
judge/needs-refinement
judge/operator-needed
judge/p0
judge/p1
judge/p2
judge/p3
judge/park
judge/patchwarden-candidate
judge/stale-priority
kind/adr
kind/bug
kind/chore
kind/feature
kind/infra
kind/ops
kind/refactor
kind/research
large-impact
merge/auto
merge/manual
merge/manual-dependency-conflict
merge/manual-failing-tests
merge/manual-merge-conflict
merge/manual-missing-review
merge/manual-operator-preference
merge/manual-red-zone
merge/manual-security-sensitive
merge/manual-unclear-scope
merge/manual-unknown
meta
mode:operator-only
mode:patchwarden-iskra-approved
mode:safe-auto
needs-operator-decision
needs-triage
not-ready
observed/erroring
observed/needs-followup
observed/pending
observed/retire-candidate
observed/unused
observed/used
operator-emotional
owner-attention
phase/02
phase/03
priority:p0
priority:p1
priority:p2
priority:p3
proposed
ready-for-agent
ready-for-operator
recovery
review:claude-reviewed
review:codex-reviewed
review:dziadek-reviewed
review:needs-human
risk/exposure
risk/process
risk/product
risk/runtime
safety:external-write
safety:no-prod-mutation
safety:prod-impact
safety:secret-touch
size/large
size/medium
size/small
size/tiny
size/unknown
source/adr
source/agent-generated
source/manual
source/operator-chat
source/voice-note
status:blocked
status:codex-ready
status:merged:pending-evidence
status:needs-evidence
status:operator-needed
status:parked
tier/full
tier/lite
tier/stacked
tier:0-platform-substrate
tier:1-iskra-value-layer
tier:2-tools-products-modules
type:bug
type:chore
type:docs
type:feat
type:policy
type:research
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
pdurlej/platform!34
No description provided.