Update GeoIntel project files

2026-07-25 23:43:08 +02:00
parent 9db6cca2b1
commit d5ea270329
155 changed files with 37970 additions and 825 deletions
@@ -1,148 +1,45 @@
-# Architecture
+# DockDeck architecture

-## 1. Overzicht
+## Runtime

-GeoIntel bestaat uit:
-
- React/TypeScript frontend
- FastAPI backend
- PostgreSQL/PostGIS database
- background job queue
- file/object storage
- GIS processing services
- AI inference services
-
-## 2. Hoofdcomponenten
+DockDeck is one deployable Node.js process. Fastify owns the REST API and serves the compiled React client in production. React/Vite provides the development UI. SQLite is mounted at `/data`; Drizzle ORM owns typed reads and writes while a small idempotent SQL migration creates the first schema before Fastify starts.

 ```text
-Frontend
-  ↓ REST/WebSocket
-FastAPI Backend
-  ↓
-PostgreSQL + PostGIS
-  ↓
-Storage: uploads, processed rasters, tiles, masks, exports
-  ↓
-Workers: GIS processing, AI inference, QA/QC, export
+Browser → Fastify API → domain rules → Drizzle → SQLite
+                       ↘ discovery service → AppOps inventory (GET only)
+                                           → Unraid XML/runtime mounts (read only)
+                                           → NPM API (read only, optional)
 ```

-## 3. Frontend
+## Trust boundaries

-Aanbevolen stack:
+- The `dockdeck` container never receives `/var/run/docker.sock`.
+- The standard deployment is exactly one `DockDeck` container. A separate `dockerproxy` exists only in the optional fallback overlay; there it is private, has `POST=0` and disables all mutation families.
+- Unraid templates are mounted read-only.
+- NPM, Gitea and provider credentials exist only as server-side process environment. Values entered in Settings are persisted in the permission-restricted environment file and remain excluded from API responses, SQLite and JSON exports.
+- Fastify validates every user-controlled mutation with Zod. External integration errors are reduced to non-sensitive connection states.
+- New discoveries are inserted with `visible=false`. Subsequent syncs update runtime fields but preserve user choices and overrides.
+- A DockDeck-only app removal records the technical name in `removed_apps`; later discovery ignores that name and never calls a Docker mutation endpoint.

- React
- TypeScript
- MapLibre GL
- Deck.gl
- Tailwind
- TanStack Query
- Zustand of vergelijkbare lichte state store
- Recharts voor eenvoudige grafieken
+## Modules

-Belangrijke principes:
+- `src/shared`: Zod contracts and pure URL/search/matching/sorting rules.
+- URL resolution prefers an explicit `br0` LAN address, then the configured Unraid host, and uses a single unambiguous published TCP port when template metadata is stale.
+- Dashboard search is a derived client index over the latest payload, so renames, removals, category changes and URL changes require no separate search persistence.
+- `src/server/database.ts`: persistence, migration, import/export and user preference invariants.
+- Widget layout is stored as validated size/content, metric order/visibility/style, statistic limit, warning and chart fields on app and preference records. Legacy rows receive safe standard/all-content defaults; version 1 backups remain compatible because added backup fields are optional on import.
+- `src/server/integrations`: read-only external adapters, provider capability metadata and deterministic mocks. Provider URLs default to an already discovered local app origin; explicit environment overrides remain available. Provider recognition is token-based and excludes known support-container roles.
+- `src/server/integrations/unraid-status.ts`: parseert een minimale read-only view van Unraid runtime- en hwmondata naar array-, parity-, opslag-, temperatuur- en optionele UPS-metrics.
+- Provideradapters bewaren alleen de laatst succesvolle gereduceerde metricresponse en een korte tijdreeks in procesgeheugen; geen van beide overleeft een procesrestart.
+- `src/server/app.ts`: narrow REST surface; no Docker control routes.
+- `src/client`: accessible responsive UI and design tokens.

- kaart centraal, maar analysepanelen even belangrijk
- labs per workflow
- duidelijke jobstatus
- outputs altijd exporteerbaar
- geen verborgen mockgedrag
+## Layout and offline model

-## 4. Backend
+Widgetvolgorde staat los van apptegelvolgorde. App- en hostrecords bewaren hun eigen volgorde; layoutpresets bevatten alleen presentatievelden, inclusief metricselectie, value/gauge/progress, waarschuwing en lijn-/vlak-/staafgrafiek. Provider- en hosthistoriek bevat maximaal zestig punten per numerieke reeks en blijft uitsluitend in procesgeheugen. Het toepassen van een preset kan geen appzichtbaarheid, navigatie-URL, credential of Dockerstaat wijzigen.

-Aanbevolen stack:
+De serviceworker cachet alleen statische applicatieshellassets. Requests onder `/api/` worden volledig overgeslagen, zodat offline content nooit als actuele runtime- of providerdata wordt gepresenteerd.

- FastAPI
- SQLAlchemy 2.x
- GeoAlchemy2
- Alembic
- Pydantic
- RQ/Celery
- Rasterio
- GeoPandas
- Shapely
- PyProj
- NumPy
- OpenCV
- Ultralytics/PyTorch
+## Failure behavior

-## 5. Database
-
-PostgreSQL met PostGIS is verplicht voor:
-
- projectgebieden
- vectorfeatures
- detectiepolygonen
- segmentatiepolygonen
- spatial joins
- intersects
- IoU berekeningen
- bounds queries
-
-## 6. Storage
-
-Bewaar grote bestanden niet in de database.
-
-Opslagcategorieën:
-
- originele uploads
- verwerkte rasters
- raster tiles
- masks
- model outputs
- exports
- rapporten
-
-Database bewaart metadata en paden.
-
-## 7. Jobs
-
-Langlopende processen moeten via background jobs:
-
- raster metadata extraction
- raster clipping
- raster tiling
- vector import
- AI inference
- segmentation polygonize
- QA/QC
- change detection
- export generation
-
-## 8. AI Inference
-
-Inference pipeline:
-
-```text
-Raster dataset
-→ clip to area
-→ tile raster
-→ normalize/preprocess
-→ model inference
-→ convert pixel coords to geospatial coords
-→ merge/filter outputs
-→ save detections/segmentations
-→ expose as map layer
-```
-
-## 9. CRS-regels
-
- Alle interne geometrieën worden opgeslagen in PostGIS met bekende SRID.
- Voor metrische berekeningen wordt een geschikte projectie gebruikt.
- API-output naar frontend mag in EPSG:4326 of WebMercator-compatible formaat.
- Elke dataset zonder CRS krijgt status `needs_crs_review`.
-
-## 10. Developmentstrategie
-
-Bouwvolgorde:
-
-1. backend foundation
-2. database schema
-3. project/area API
-4. dataset upload en metadata
-5. frontend workspace en kaart
-6. vector import
-7. raster import
-8. processing jobs
-9. detection lab
-10. QA/QC
-11. export
+Saved data is always returned independently of integration health. A failed AppOps inventory, missing Unraid mount or unavailable NPM instance produces a degraded integration card/banner without blocking navigation. Polling runs only while the browser tab is visible. AppOps inventory is read immediately; its slower all-container resource sample refreshes in the background so it cannot delay navigation.
@@ -0,0 +1,29 @@
+# Authenticated external access
+
+DockDeck has no built-in authentication. Keep its Compose bind on `127.0.0.1` or a trusted LAN address unless an authenticated HTTPS reverse proxy protects every route.
+
+## Recommended topology
+
+```text
+Internet -> HTTPS reverse proxy -> Authentik forward auth -> DockDeck :1218
+Trusted LAN -----------------------------------------------> DockDeck :1218
+```
+
+## Minimum requirements
+
+1. Terminate TLS with a valid certificate.
+2. Require authentication before proxying `/`, static assets and every `/api/*` route.
+3. Do not create an unauthenticated exception for `/api/diagnostics`, integration settings or exports.
+4. Preserve the original host and forwarding headers.
+5. Restrict the upstream to `http://192.168.10.150:1218`; never publish the internal Docker socket proxy.
+6. Use a separate minimum-scope account/token for each provider and protect `/data/integrations.env` backups.
+
+## Validation checklist
+
+- An incognito request is redirected to authentication before DockDeck HTML or API JSON is returned.
+- A signed-in user can load the dashboard, search, edit a harmless presentation preference and read diagnostics.
+- Signing out invalidates both page and API access.
+- The browser reports HTTPS without mixed content.
+- The reverse proxy does not cache `/api/*` responses.
+
+Nginx Proxy Manager discovery in DockDeck remains read-only and does not create or change proxy hosts. Proxy and Authentik configuration therefore stay an explicit deployment responsibility.
@@ -0,0 +1,37 @@
+# DockDeck implementation status
+
+Updated: 2026-07-22
+
+| MVP criterion                                     | Status        | Evidence                                                                                                                  |
+| ------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| Read-only Docker/Unraid discovery                 | Live verified | AppOps GET adapter, optional restricted proxy overlay, mocks and adapter tests.                                           |
+| New containers hidden                             | Built         | Repository insert invariant and API/database tests.                                                                       |
+| App visibility/name/category/order/URL management | Built         | Settings UI, Zod API and persistence tests.                                                                               |
+| Persistent app removal                            | Verified      | DockDeck-only delete endpoint, `removed_apps` suppression and rediscovery/export coverage.                                |
+| Local WebUI detection                             | Built         | Unraid XML parser, port substitution and unit tests.                                                                      |
+| Status and ~30 second polling                     | Built         | Runtime state mapping and visibility-aware client interval.                                                               |
+| Categories and both dashboard views               | Built         | CRUD API, settings and responsive overview/tab UI.                                                                        |
+| Favorites                                         | Built         | CRUD API, settings, dashboard tiles and search index.                                                                     |
+| Search and Google fallback                        | Verified      | Dynamic full-payload index, keyboard selection, explicit Google action and browser flow.                                  |
+| Links open in new tabs                            | Built         | All tiles/results use `_blank` with `noopener noreferrer`.                                                                |
+| Three themes                                      | Built         | Porcelain, Midnight and Harbor tokens and controls.                                                                       |
+| Persistent appearance customization               | Verified      | Theme, mode, accent, density, width, background, hero, status, reduced motion and polling with migration/export coverage. |
+| Searchable settings                               | Verified      | Global section search, accessible controls and automatic scroll restoration on section changes.                           |
+| Read-only service widgets                         | Verified      | Per-app opt-in, eight-widget limit, domain data, three sizes, four layers and configurable presentation.                  |
+| Configurable Tower identity                       | Live verified | Persistent server name/URL in Settings, search and host card; live URL is `192.168.10.150:5000`.                          |
+| Automatic favorite favicons                       | Verified      | First-party `/favicon.ico` derivation, explicit override and monogram fallback.                                           |
+| SQLite persistence                                | Built         | Named Docker volume and restart persistence test.                                                                         |
+| Export/import                                     | Built         | Versioned Zod schema, API and settings flow; secrets excluded.                                                            |
+| Read-only NPM integration                         | Built         | Optional server-side adapter, unambiguous matching and fallback.                                                          |
+| Degraded states                                   | Built         | Adapter isolation, health states, banner and integration panel.                                                           |
+| Docker/Unraid packaging                           | Live verified | Commit `3ffd39b`, one healthy `DockDeck` on `192.168.10.150:1218`; 137 stored/55 visible apps and 90 GET-only containers. |
+| Private Gitea repository                          | Verified      | Private `NuklearRabbit/DockDeck`; local `main` tracks `origin/main`.                                                      |
+| Professional responsive UI                        | Live verified | 390px through ultrawide plus live 1280×720; adaptive cards, persistent favorites sidebar and no overflow.                 |
+| Independent widget composition                    | Verified      | Order, size, content, labels, metric styles/limits, any-signal warnings, cadence, charts and edit mode.                   |
+| Native Unraid health                              | Live verified | Array STARTED, parity healthy, three storage groups and temperatures through read-only mounts.                            |
+| App-specific provider breadth                     | Live verified | 97/97 stored apps have an explicit domain profile; zero generic profiles remain in the live capability audit.             |
+| Per-app metric composition                        | Live verified | Labels can be selected, ordered, styled, limited, charted and monitored and survive presets/export/restart.               |
+| Configurable Unraid trends                        | Live verified | Container, image, storage, temperature, parity and UPS series with statistic selection and 60-point memory.               |
+| Unraid Docker-list icon                           | Live verified | DockerMan visibly renders the 512×512 PNG after both persistent and active caches are refreshed.                          |
+| Layout presets                                    | Verified      | Create, apply, delete and independent import/export with database/API/browser coverage.                                   |
+| PWA and diagnostics                               | Live verified | Installable shell excludes `/api`; diagnostics are secret-free and report native/integration health.                      |
@@ -0,0 +1,75 @@
+# DockDeck platform audit
+
+Updated: 2026-07-15
+
+## Executive assessment
+
+DockDeck is now a complete daily-use dashboard rather than a launcher with generic telemetry. Navigation, app management, responsive presentation, widget composition, service-specific data, Unraid host depth, freshness, portability and diagnostics form one coherent read-only product. The P0, P1 and P2 roadmap from the previous audit is implemented.
+
+## Current scorecard
+
+| Area                  | Assessment             | Evidence                                                                                                         |
+| --------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| Navigation and search | Complete               | Dynamic index follows renames, removals, URLs, categories, favorites and Tower.                                  |
+| Responsive shell      | Complete               | Mobile, tablet, desktop and ultrawide layouts have no positive horizontal overflow.                              |
+| App management        | Complete               | Rename, override, categorize, hide and persistent DockDeck-only removal.                                         |
+| Widget composition    | Complete               | Order, three sizes, content layers, per-metric visibility/order/style, limits, labels, warnings and edit mode.   |
+| Widget data depth     | Complete framework     | Live audit: 97/97 apps have a specific capability profile, zero generic profiles; 23 native providers.           |
+| Unraid host depth     | Complete               | AppOps plus array/parity/storage/temperature/UPS, selectable stats and configurable server trend charts.         |
+| Freshness and trends  | Complete               | Fresh/stale/unavailable semantics, cadence, stale cache and selectable line/area/bar charts up to sixty samples. |
+| Portability           | Complete               | Full secret-free backup plus independent layout preset import/export.                                            |
+| Operations            | Complete for LAN       | Secret-free diagnostics, health endpoint, PWA shell and authenticated reverse-proxy guide.                       |
+| Security              | Strong for trusted LAN | Single socketless container, GET-only integrations, masked secrets and API-excluding service worker.             |
+
+## Delivered roadmap
+
+### Personal widget depth
+
+- Persistent Tower name and URL in Settings with port `5000` as the default Unraid WebUI route.
+- Capability coverage expanded from a provider shortlist to every discovered app.
+- Native Audiobookshelf, Netdata and PeerTube readers added to the existing provider set.
+- Domain profiles for the actual live inventory, including app/API/frontend/worker/database/cache, mail, GPU, download, media, document and custom-project workloads.
+- Per-app metric visibility and ordering, including dynamically returned labels and preset/export persistence.
+- Per-app value/gauge/progress presentation, statistic limits, line/area/bar charts, legends and selectable 10–60 sample windows.
+- Warning rules can target any numeric infrastructure or provider metric and trigger above or below the configured value.
+- Capability labels remain app-specific before an endpoint is connected; absent values say `Connect data` instead of showing unrelated generic Docker labels.
+- BlockPilot root/runtime/API/web/Minecraft/ViaProxy, LumaOps, Chimera, OpenRGB, Porkfolio and unnamed legacy workloads now have explicit profiles rather than the last generic service profile.
+- Tower exposes selectable/ordered server statistics and charts for containers, images, storage, temperature, parity and UPS.
+- A constrained custom contract (`summary` plus at most twelve stats) for apps without a native read API; endpoint and optional bearer token are configured in Widget Studio and remain server-side.
+
+### P0
+
+- Independent widget order with keyboard-accessible move controls.
+- Native Unraid adapter for array state, parity, disk/pool usage, temperatures and optional UPS data.
+- App-specific Gitea adapter and GET-only metrics bridges for Deluge, JDownloader and Tdarr.
+- Explicit freshness states with last-successful provider cache.
+
+### P1
+
+- Metric order, primary metric, custom labels and numeric provider/infrastructure warning thresholds.
+- Saved, applicable, removable and portable layout presets.
+- Safe per-widget refresh cadence between 15 seconds and 5 minutes.
+- Direct dashboard edit mode with move, resize and hide controls.
+- Provider expansion for Jellyfin, Seerr, Prowlarr, Authentik, NPM, Portainer, Grafana, Prometheus and Nextcloud, plus bridges for qBittorrent, Bazarr and Vaultwarden.
+
+### P2
+
+- Selectable line, area and bar charts with at most sixty in-memory points and no monitoring database.
+- Installable PWA application shell; API responses are never cached.
+- Independent preset export/import.
+- Secret-free diagnostics and an authenticated external-access guide.
+
+## Remaining environment-dependent opportunities
+
+- Fill provider credentials or bridge URLs in Settings only for services whose protected API data is desired. Safe Docker fallback remains available without them.
+- Configure `UNRAID_UPS_STATUS_PATH` only when a stable read-only APC/UPS status file is available on the host.
+- Enable external access only behind authenticated HTTPS; DockDeck deliberately has no built-in user system.
+- Persistent long-term history, alerts and notifications remain intentionally outside scope. They would turn DockDeck into a monitoring platform and need separate retention and delivery decisions.
+
+## Guardrails
+
+- A widget is app-specific only when its metrics describe the real workload of that app.
+- Every external request remains GET-only, time-bounded and server-side.
+- Provider failure never blocks navigation and always falls back to safe telemetry.
+- Compact panels answer one question, standard panels a few, and wide panels may expose deeper context.
+- Layout remains fully usable without drag-and-drop and is tested at both mobile and ultrawide sizes.
@@ -0,0 +1,9 @@
+# DockDeck design system
+
+De visuele basis is **DockDeck Canon v1**. Het onderhoudbare systeem, de bronselectie en de mapping naar echte productflows staan in:
+
+- [`dockdeck-canon-v1/DESIGN_SYSTEM.md`](./dockdeck-canon-v1/DESIGN_SYSTEM.md)
+- [`dockdeck-canon-v1/SOURCE_MANIFEST.md`](./dockdeck-canon-v1/SOURCE_MANIFEST.md)
+- [`dockdeck-canon-v1/IMPLEMENTATION_MAPPING.md`](./dockdeck-canon-v1/IMPLEMENTATION_MAPPING.md)
+
+Gebruik in productcode uitsluitend semantische tokens en lokale assets. Behoud dark en light themes, Nederlandse terminologie, echte API-data en de read-only productgrenzen.
@@ -0,0 +1,68 @@
+# Stitch Canon UI-upgradeplan
+
+Datum: 2026-07-21  
+Branch: `codex/stitch-canon-ui-upgrade`
+
+## Nulmeting
+
+DockDeck is een React/Vite-single-page-app met Fastify REST, SQLite en gedeelde Zod-contracten. `App.tsx` beheert dashboard/settings, polling, themadata-attributen en toasts. `Dashboard.tsx` groepeert echte apps en favorieten. `Settings.tsx` bevat de bestaande beheerflows; widgetconfiguratie blijft in afzonderlijke componenten. Er is geen router: schermwisseling is lokale React-state.
+
+De bestaande functionaliteit is operationeel, maar de interface wijkt zichtbaar van Canon v1 af: Engelse copy, een permanente brede dashboardrail, een prominente monitoringlaag vóór de launcherinhoud en volledig uitgeklapte appformulieren. De baseline is opgeslagen onder `.codex-input/baseline/`.
+
+Baselinechecks:
+
+- format, lint en typecheck: geslaagd;
+- unit/integratie: 42/42 geslaagd;
+- security: 5/5 geslaagd;
+- build en audit: geslaagd, 0 kwetsbaarheden;
+- E2E-start: omgevingsblokkade doordat een WSL-relay poort 3000 bezet; de upgrade maakt de testpoort configureerbaar.
+
+## Routes en workflows
+
+| Oppervlak         | Werkelijke workflow                                                                  | Canonvertaling                                                                                   |
+| ----------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
+| Dashboard         | apps/favorieten openen, categorieën, sync, widgets                                   | compacte topbar, Quick Launch eerst, favorieten en apps als launcher; widgets lager en optioneel |
+| Quick Launch      | apps/favorieten/Tower/Google, toetsenbord                                            | gegroepeerde command-palette met Apps, Favorieten en Google                                      |
+| Apps              | zoeken, zichtbaarheid, widget, naam, categorie, URL's, icoon, sortering, verwijderen | compacte beheerregels met filters en een app-editor drawer                                       |
+| Favorieten        | toevoegen, wijzigen, verwijderen                                                     | Canon-lijst plus rustig formulier/drawerpatroon                                                  |
+| Categorieën       | toevoegen, wijzigen, icoon, sortering, verwijderen                                   | Canon-lijst met duidelijke aantallen en inline-acties                                            |
+| Weergave          | thema, accent, dichtheid, breedte, achtergrond, hero/status, modus                   | visuele keuzevelden en previews binnen dezelfde settings-shell                                   |
+| Widgets/operaties | bestaande read-only panelen, presets en diagnostics                                  | behouden onder Algemeen als secundaire geavanceerde functies                                     |
+| Integraties       | status en gemaskeerde credentials                                                    | doelgerichte read-only statuskaarten zonder secret-echo                                          |
+| Back-up           | export/import versie 1                                                               | Canon back-up- en hersteloppervlak, zonder fictieve historie                                     |
+
+## Componentstrategie
+
+Hergebruikt: API-client, contracten, URL-resolutie, iconpipeline, widgetconfigurators, server- en servicewidgets, persistence en alle backendvalidatie.
+
+Herbouwd of toegevoegd: semantische tokenlaag, lokale merkassets, `DashboardTopBar`, dashboardcompositie, categorie-navigatie, app-/favoriettegels, Quick Launch-groepering, settings-shell, compacte appbeheerregels, app-editor drawer, banners, empty/loading/degraded states en mobiele navigatie.
+
+## Tokens en responsiviteit
+
+Canon v1 gebruikt een 8px-basis, diepe navy, tonale oppervlakken, lavendel voor actie/focus en groen uitsluitend voor positieve status. Dark, light en het bestaande aanvullende thema blijven functioneel via semantische CSS-variabelen. Bestaande accenten blijven beschikbaar maar worden op de Canon-tokenlaag geprojecteerd.
+
+- 1920×1080 en 1440×900: max. 1280px launcherinhoud, compacte topbar, vier appkolommen waar passend.
+- 768–1024px: twee kolommen, compacte settingsnavigatie.
+- 390×844: echte mobiele compositie, horizontaal scrollbare categorieën, één/twee kolommen naar inhoud, vaste ondernavigatie.
+- Geen horizontale overflow; minimum klikdoel 44px; `prefers-reduced-motion` blijft leidend.
+
+## Risico's en mitigatie
+
+- De huidige widgetdiepgang is groter dan de statische Canon-scope. De functies blijven bestaan maar verdwijnen uit de primaire launcherhiërarchie.
+- `Settings.tsx` is groot. De wijziging beperkt backend/API-impact en splitst nieuwe UI-primitives en drawerlogica waar dat reviewbaarheid verbetert.
+- E2E gebruikt een vaste poort. De configuratie krijgt een geïsoleerde testpoort zonder productieruntime te wijzigen.
+- Externe appiconen kunnen falen. De bestaande veilige monogramfallback blijft behouden.
+
+## Validatie
+
+Twee visuele rondes vergelijken dark/light dashboard, Quick Launch, settings/apps, editor en mobiel met de referenties. Daarna volgen alle verplichte scripts, browserconsole/netwerkcontrole, overflowchecks op 390×844, 768×1024, 1440×900 en 1920×1080, Compose-config en een Docker-imagebuild wanneer de lokale Docker-runtime beschikbaar is.
+
+## Niet-doelen
+
+Geen Docker-mutaties, containerbeheer, accounts, terminal/logviewer, nieuwe backendintegraties, fictieve data, automatische back-uphistorie of externe tijdelijke assets.
+
+## Resultaat
+
+Afgerond op 2026-07-21. De Canon-tokenlaag, lokale Geist-fonts, merkassets, topbar, launcherhiërarchie, Quick Launch, compacte settings-shell, app-editor drawer en responsive mobiele compositie zijn in de bestaande React/Fastify-app geïntegreerd. De E2E-runtime gebruikt geïsoleerde poorten 3101/5174 zodat een lokale WSL-relay op 3000 de suite niet meer blokkeert. De finale gates en eventuele resterende omgevingsbeperkingen staan in `TEST_LOG.md`, `RISKS.md` en `HANDOFF.md`.
+
+Een aanvullende fidelity-pass heeft de eerder nog eigen DockDeck-interpretatie vervangen door de daadwerkelijke `canon_*`-compositie. Stitch bepaalt nu vrijwel volledig layout, density, kaartfamilies, navigatie, overlay, settings-tabel, drawer en mobiele hiërarchie; alleen echte data, bestaande validatie en operationele workflows wijken bewust af van de statische voorbeelden.
@@ -0,0 +1,30 @@
+# DockDeck Canon v1
+
+DockDeck is een rustige, premium digitale thuisbasis. De interface is een launcher, geen beheer- of monitoringconsole.
+
+## Fundament
+
+- 8px spacingbasis; 16px mobiel zijmarge, 24px desktopgutter, 1280px launchermaximum.
+- Geist-achtige lokaal gebundelde sans-serif, sentence case en volledig Nederlandse copy met `je/jouw`.
+- Dark-first diepe navy `#0b1326`; tonale oppervlakken en subtiele 1px-randen.
+- Lavendel `#818cf8` voor merk, focus, selectie en primaire acties.
+- Groen `#10b981` uitsluitend voor positieve status/bevestiging; rood voor offline/fout, slate voor onbekend.
+- 8px radius voor controls, 12–16px voor grotere oppervlakken, pills alleen waar de vorm betekenis heeft.
+- Geen zware schaduwen of permanente pulserende statusanimaties.
+
+## Semantische tokens
+
+Productcode gebruikt tokens voor `background`, `surface`, `surface-elevated`, `border`, `text`, `text-muted`, `primary`, `focus`, `success`, `warning`, `error`, `unknown`, `hover`, `active` en `disabled`. Thema's wijzigen de tokenwaarden, niet de componentstructuur.
+
+## Componentregels
+
+- Apptegels tonen icoon, naam en `Online`, `Offline` of `Status onbekend`; geen poort, image, CPU, RAM of uptime.
+- Favoriettegels delen dezelfde visuele familie zonder runtimestatus.
+- Quick Launch groepeert Apps, Favorieten en Google en ondersteunt muis en toetsenbord.
+- Settings gebruikt één shell met Algemeen, Apps, Favorieten, Categorieën, Weergave, Integraties en Back-up en herstel.
+- Overlays hebben Escape, focusherstel en een zichtbaar sluitdoel; drawer op desktop, schermvullend op mobiel.
+- Status wordt nooit uitsluitend met kleur gecommuniceerd.
+
+## Assets
+
+Alle merkassets, fonts en productie-iconen zijn lokaal. Stitch-screenshots zijn alleen ontwerpdocumentatie; HTML/CDN/Google-hosted exportassets worden niet uitgevoerd of gebundeld.
@@ -0,0 +1,37 @@
+# Implementatiemapping — DockDeck Canon v1
+
+| Canonreferentie                               | DockDeck-oppervlak              | Implementatiekeuze                                                                                                 |
+| --------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| Dashboard 1440/1920 donker                    | primaire startpagina            | compacte topbar, begroeting, categorieën, desktopfavorietenrail, apptegels en uitklapbaar live inzicht; echte data |
+| Dashboard licht                               | light theme                     | dezelfde hiërarchie en componentvormen op lichte semantische tokens                                                |
+| Dashboard categorie-modus                     | bestaande `viewMode=categories` | categoriechips sturen de bestaande filterlogica                                                                    |
+| Quick Launch resultaten/geen lokaal resultaat | `SearchOverlay`                 | viewportbrede portal met Apps/Favorieten/Google, pijlen, Enter, Escape en herstelde toetsenbordfocus               |
+| Instellingen Apps                             | `Settings` / apps               | compacte rijen, echte ontdekstatus, filters, paginering en status/zichtbaarheid afzonderlijk                       |
+| App-editor drawer                             | app PATCH-contract              | naam, zichtbaarheid/categorie, lokale/externe URL, icoon en sortering in toegankelijke drawer                      |
+| Instellingen Favorieten                       | favoriete CRUD                  | Canon-lijst en formulier met bestaande validatie                                                                   |
+| Instellingen Categorieën                      | categorie CRUD                  | bestaande naam/icoon/sortering/verwijderen in rustige lijst                                                        |
+| Instellingen Weergave                         | preferences PATCH               | thema, modus en dichtheid eerst; accent, breedte, achtergrond en details progressief ontsloten                     |
+| Instellingen Integraties                      | status/credential-API           | uitsluitend bestaande read-only integraties; secrets gemaskeerd                                                    |
+| Back-up en herstel                            | `/api/export` en `/api/import`  | bestaande versie 1-flow, geen fictieve historie                                                                    |
+| Mobiel 390×844                                | responsive dashboard/settings   | mobiele topbar, touchcategorieën, compacte tegels en ondernavigatie                                                |
+
+## Bewuste afwijkingen
+
+- Bestaande read-only widgets, presets en diagnostics blijven beschikbaar onder Algemeen omdat dit operationele productfunctionaliteit is; ze krijgen geen voorrang boven de launcher.
+- De statische voorbeelden gebruiken andere apps en aantallen; DockDeck toont uitsluitend API-data.
+- Canon-copy over Docker Proxy wordt niet letterlijk gebruikt omdat productie via AppOps kan ontdekken; integratietekst volgt de echte runtime.
+- Het logo wordt vereenvoudigd voor 16–48px en als lokaal SVG/PNG geleverd; de bronafbeelding wordt niet uitgesneden of gehotlinkt.
+
+## Implementatiestatus
+
+Alle bovenstaande kernoppervlakken zijn op 2026-07-21 geïmplementeerd. Het dashboard gebruikt de echte API-payload, Quick Launch groepeert server/apps/favorieten/Google, appbeheer gebruikt compacte regels plus een focus-trapped drawer en de bestaande geavanceerde widget- en diagnosticaflows staan onder **Algemeen**. De statische Canon-voorbeelden zijn dus niet als los prototype of hardcoded datalaag overgenomen.
+
+Na de eerste review is een tweede, directere Stitch-pass uitgevoerd. `stitch-direct.css` is de finale compositielaag en neemt nu de daadwerkelijke Canon-hiërarchie over: 64px topbar, begroeting met compacte ontdekbanner, pilnavigatie, vaste favorietkaart, vierkoloms servicekaarten, tweekoloms featurekaarten, de volledige Quick Launch-sheet, App Beheer als vijfkolomstabel en de 570px app-editor. Op mobiel worden de ontdekkaart, zoekbalk, ronde categorieknoppen, favorietegels, compacte servicerijen en vaste ondernavigatie rechtstreeks uit `canon_mobiel_dashboard_390_844` gevolgd.
+
+Het operationele widgetblok blijft in de normale launcher zichtbaar als compacte rij **Live inzicht** en klapt op verzoek open. De volledige Paneelstudio, presets en diagnostics blijven onder **Algemeen** beschikbaar, zodat de dagelijkse launcher rustig blijft zonder functionaliteit te verbergen.
+
+De visuele eindcontrole staat in [`implementation/README.md`](./implementation/README.md). Daarbij is ook de eerste-use toestand met alle nieuw ontdekte apps verborgen gecontroleerd; de gevulde screenshots gebruiken uitsluitend de geïsoleerde mockdatabase onder `.codex-input/`.
+
+## Consistentiepass 2026-07-22
+
+Dashboard en instellingen delen nu dezelfde platformgeometrie tot 3040 px, met een schaalbare linkerrail en een rechter widgetdock dat vanaf 1900 px automatisch opent. De instellingenkopie en form controls zijn vergroot voor leesbaarheid, apptegels hebben sterkere iconografie en actieaffordances, Quick Launch gebruikt echte favorieticonen en de lege zoekstaat bevat directe snelkoppelingen in plaats van alleen uitlegtekst.
@@ -0,0 +1,23 @@
+# Source manifest — DockDeck Canon v1
+
+## ZIP
+
+- Bron: `C:\Users\Jens\Downloads\stitch_dockdeck_premium_interface_system (2).zip`
+- SHA-256: `C5A76D95680550A74024F967F86553A008E5657C05833EE13C042C4F493BD441`
+- Tijdelijke extractie: `.codex-input/stitch-dockdeck-canon-v1/` (genegeerd door Git)
+- Primair: `dockdeck_canon_v1/DESIGN.md`, `dockdeck_canon_logo/screen.png` en alle `canon_*`-schermen.
+- Aanvullende controle: `design.md_dockdeck_canon_v1.md`.
+- Bewust genegeerd: `core_modernist/`, `obsidian_control/`, niet-`canon_*` schermen, `*_definitief` varianten en conflicterende oudere designsystemen.
+
+## Stitch MCP
+
+- Beschikbaar op 2026-07-21.
+- Project: `projects/11417268779858336248` — **DockDeck Premium Interface System**.
+- Project bijgewerkt: 2026-07-21T19:14:24.395101Z.
+- Gebruikt design system: `assets/d3776abdbc9040bcac889ef9b20c3eb8` — **DockDeck Canon v1**, versie 1.
+- Gecontroleerde metadata: Geist, dark-first, 8px afronding, `#818cf8` primair, `#10b981` positief, `#0b1326` basis en 1280px contentmaximum.
+- De actuele `CANON — ...` schermen zijn vergeleken; niet-canonieke oudere schermen en de systemen Obsidian Control/Core Modernist zijn niet als productbron gebruikt.
+
+## Opgenomen referenties
+
+De map `screens/` bevat alleen dashboard dark/light, Quick Launch-resultaten, instellingen Apps, mobiel dashboard en de logo-referentie. HTML-export en externe Google-assets zijn niet opgenomen of gebruikt als productieafhankelijkheid.
@@ -0,0 +1,20 @@
+# Canon v1 implementatiebeelden
+
+Deze beelden zijn op 2026-07-22 rechtstreeks uit de lokale applicatie vastgelegd met deterministische mockdiscovery. Ze bevatten geen credentials of productiegegevens. De actuele dashboards tonen de Stitch-launcherworkspace met desktopfavorietenrail, herkenbare appiconen en zichtbare read-only servicepanelen; de E2E-suite legt ze opnieuw vast.
+
+| Oppervlak                                 | Beeld                                                                                    |
+| ----------------------------------------- | ---------------------------------------------------------------------------------------- |
+| Dashboard licht, desktop 1440×900         | [`dashboard-light-desktop-1440x900.png`](./dashboard-light-desktop-1440x900.png)         |
+| Dashboard donker, desktop 1440×900        | [`dashboard-dark-desktop-1440x900.png`](./dashboard-dark-desktop-1440x900.png)           |
+| Quick Launch licht, desktop 1440×900      | [`quick-launch-light-desktop-1440x900.png`](./quick-launch-light-desktop-1440x900.png)   |
+| Apps-instellingen licht, desktop 1440×900 | [`settings-apps-light-desktop-1440x900.png`](./settings-apps-light-desktop-1440x900.png) |
+| Dashboard licht, mobiel 390×844           | [`dashboard-light-mobile-390x844.png`](./dashboard-light-mobile-390x844.png)             |
+| App-editor drawer, mobiel 390×844         | [`app-drawer-mobile-390x844.png`](./app-drawer-mobile-390x844.png)                       |
+| Dashboard donker, mobiel 390×844          | [`dashboard-dark-mobile-390x844.png`](./dashboard-dark-mobile-390x844.png)               |
+| Dashboard donker, tablet 768×1024         | [`dashboard-dark-tablet-768x1024.png`](./dashboard-dark-tablet-768x1024.png)             |
+| Dashboard donker, ultrawide 3440×1440     | [`dashboard-dark-ultrawide-3440x1440.png`](./dashboard-dark-ultrawide-3440x1440.png)     |
+| Quick Launch donker, desktop 1440×900     | [`quick-launch-dark-desktop-1440x900.png`](./quick-launch-dark-desktop-1440x900.png)     |
+| Apps-instellingen donker, desktop         | [`settings-apps-dark-desktop-1440x900.png`](./settings-apps-dark-desktop-1440x900.png)   |
+| App-editor donker, desktop                | [`app-drawer-dark-desktop-1440x900.png`](./app-drawer-dark-desktop-1440x900.png)         |
+
+De geïsoleerde E2E-database wordt alleen voor visuele verificatie aangepast om drie apps en drie favorieten zichtbaar te maken. De productregel blijft ongewijzigd: nieuw ontdekte apps zijn standaard verborgen. De finale audit controleert bovendien alle instellingensecties, de horizontale tablet-/mobiele navigatie, echte appiconen, de uitklapbare widgetlaag en een Quick Launch die ook op ultrawide het volledige viewport afdekt.