First version of Karten App

2026-10-09 04:20:40 +02:00
commit 83a36c7a22
41 changed files with 10834 additions and 0 deletions
@@ -0,0 +1,9 @@
+---
+status: accepted
+---
+
+# Offline PWA with prepared raster tiles
+
+The Karte is an installable app for phone and tablet, with no app store and no live map server. The Mac turns the DTK25 Blätter into Kacheln once. A Kachel reaches the device because the user downloads a Gebiet, or because the open Karte needs it and the device is online. The open Karte reads only the Kacheln inside the current view. The furthest zoom-out is a ground span shipped in the app configuration, 36 km by 36 km unless that file is changed. The prepared Kacheln cover every scale from that span down to the native sheet pixel. Downloading a Gebiet fetches all of those scales, the current view first. Downloads run only while that app is open and the device is online; leaving the app pauses them, and opening it again continues them. Which of those Kacheln a delete keeps is [ADR 0002](0002-cached-tiles-follow-downloaded-gebiete.md).
+
+A macOS desktop app was rejected. Serving the original GeoTIFFs from the Mac while the phone is on the same network was rejected, because the Karte has to work after the download, with that computer left behind.
@@ -0,0 +1,9 @@
+---
+status: accepted
+---
+
+# Cached Kacheln follow the Gebiete still marked downloaded
+
+A Gebiet is marked heruntergeladen when its download starts, before every Kachel has arrived. Deleting it stops the rest of that download, then removes every Kachel of that Gebiet from the Cache, except a Kachel that also lies in another Gebiet still marked heruntergeladen. Deleting the whole Cache removes every Kachel and clears every heruntergeladen mark. On-demand Kacheln have no protection of their own. Usingen overlapping Wehrheim is the test: after Wehrheim is removed, a Kachel in both stays because Usingen is still heruntergeladen. After Hessen is removed, a Kachel stays only where a smaller Gebiet such as Usingen or Wehrheim is still heruntergeladen.
+
+The alternative was to remember which download fetched each Kachel, and to keep every on-demand Kachel until the whole Cache is deleted. That was rejected: removing Hessen clears Hessen even when those Kacheln arrived by panning.
@@ -0,0 +1,51 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root, or
+- **`CONTEXT-MAP.md`** at the repo root if it exists: it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`**: read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+Single-context repo (most repos):
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/adr/                          ← system-wide decisions
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md
+    │   └── docs/adr/                  ← context-specific decisions
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/adr/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal: either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders), but worth reopening because…_
@@ -0,0 +1,30 @@
+# Issue tracker: Local Markdown
+
+Issues and specs for this repo live as markdown files in `.scratch/`.
+
+## Conventions
+
+- One feature per directory: `.scratch/<feature-slug>/`
+- The spec is `.scratch/<feature-slug>/spec.md`
+- Implementation issues are one file per ticket at `.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01`, never a single combined tickets file
+- Triage state is recorded as a `Status:` line near the top of each issue file (see `triage-labels.md` for the role strings)
+- Comments and conversation history append to the bottom of the file under a `## Comments` heading
+
+## When a skill says "publish to the issue tracker"
+
+Create a new file under `.scratch/<feature-slug>/` (creating the directory if needed).
+
+## When a skill says "fetch the relevant ticket"
+
+Read the file at the referenced path. The user will normally pass the path or the issue number directly.
+
+## Wayfinding operations
+
+Used by `/wayfinder`. The **map** is a file with one **child** file per ticket.
+
+- **Map**: `.scratch/<effort>/map.md` (the Notes / Decisions-so-far / Fog body).
+- **Child ticket**: `.scratch/<effort>/issues/NN-<slug>.md`, numbered from `01`, with the question in the body. A `Type:` line records the ticket type (`research`/`prototype`/`grilling`/`task`); a `Status:` line records `claimed`/`resolved`.
+- **Blocking**: a `Blocked by: NN, NN` line near the top. A ticket is unblocked when every file it lists is `resolved`.
+- **Frontier**: scan `.scratch/<effort>/issues/` for files that are open, unblocked, and unclaimed; first by number wins.
+- **Claim**: set `Status: claimed` and save before any work.
+- **Resolve**: append the answer under an `## Answer` heading, set `Status: resolved`, then append a context pointer (gist + link) to the map's Decisions-so-far in `map.md`.
@@ -0,0 +1,15 @@
+# Triage Labels
+
+The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
+
+| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
+| -------------------------- | -------------------- | ---------------------------------------- |
+| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
+| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
+| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
+| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
+| `wontfix`                  | `wontfix`            | Will not be actioned                     |
+
+When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
+
+Edit the right-hand column to match whatever vocabulary you actually use.