docs: capture protocol and implementation gaps

notes/discrepancies.md

@@ -0,0 +1,10 @@
+# Documentation Discrepancies
+
+## 2026-04-28
+
+1. The plan and ADRs repeatedly describe a single Go binary, while Milestone 1 also requires `apps/web/` as a separate Vite/Preact app. The current implementation treats the web app as build-time static assets served by the Go binary.
+2. Milestone 1 asks for `packages/protocol/` with a protobuf schema, but the sync ADR and protocol spec describe JSON messages over WebSocket. The protocol package currently preserves both a `.proto` placeholder and TypeScript-facing JSON model notes.
+3. ADR-005 stores content under `data/files/...`, while Milestone 2 examples use `store/...`. The implementation follows ADR-005 and uses `data/files`.
+4. ADR-007 says "No build scripts: Makefile only — no npm install," but the chosen frontend stack requires a Node package install step. The Makefile centralizes it, but the dependency policy needs clarification.
+5. The foundation milestone specifies `golang-migrate`, but `go-libsql` integration constraints need a clean validation path. A lightweight internal migrator is used now so the project can move forward.
+

notes/problems.md

@@ -0,0 +1,9 @@
+# Implementation Problems Log
+
+## 2026-04-28
+
+- `go-libsql` is the active official Go binding, but it requires CGO and precompiled native libraries. That weakens the "same source -> same binary hash" goal until the exact build environment is locked down.
+- The embedded-replica connector in `go-libsql` rejects an empty primary URL. The foundation therefore uses the local `file:` libsql driver path when no primary is configured, and reserves embedded-replica setup for later sync work.
+- Docker verification is currently blocked by the local environment because the daemon socket at `/Users/tim/.orbstack/run/docker.sock` was not reachable during `docker build`.
+- The docs do not define a config file format. This implementation uses JSON to keep the bootstrap dependency-free.
+- The docs require "all Markdown extensions" but do not define a canonical sample corpus. A representative content sample is included and should be expanded as renderer coverage grows.

openapi/openapi.yaml

@@ -0,0 +1,56 @@
+openapi: 3.1.0
+info:
+  title: MD Hub Secure Foundation API
+  version: 0.1.0
+servers:
+  - url: http://localhost:8080
+paths:
+  /health:
+    get:
+      summary: Health check
+      operationId: getHealth
+      responses:
+        "200":
+          description: Healthy
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status:
+                    type: string
+                  database:
+                    type: string
+                  contentStore:
+                    type: string
+  /api/uploads:
+    post:
+      summary: Upload a single attachment
+      operationId: uploadAttachment
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              properties:
+                file:
+                  type: string
+                  format: binary
+      responses:
+        "201":
+          description: Attachment stored
+  /attachments/{hash}:
+    get:
+      summary: Download an attachment by content hash
+      operationId: getAttachment
+      parameters:
+        - in: path
+          name: hash
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Attachment content
+

packages/protocol/README.md

@@ -0,0 +1,11 @@
+# Protocol Package
+
+This directory exists because the milestone plan expects a shared protocol package.
+
+For now:
+
+- `simplesync.proto` captures an eventual strongly typed schema
+- `docs/specs/simplesync-protocol.md` remains the more complete behavioral reference
+
+The current docs still need a final decision on whether wire messages are JSON, protobuf-over-WebSocket, or JSON generated from protobuf definitions.
+

packages/protocol/simplesync.proto

@@ -0,0 +1,28 @@
+syntax = "proto3";
+
+package mdhub.protocol.v1;
+
+option go_package = "github.com/tim/md-hub-secure/packages/protocol/gen/go/mdhub/protocol/v1;protocolv1";
+
+message SyncRequest {
+  string client_id = 1;
+  string root_hash = 2;
+  map<string, string> files = 3;
+}
+
+message SyncResponse {
+  string server_root_hash = 1;
+  repeated string missing_from_client = 2;
+  repeated string missing_from_server = 3;
+  repeated string conflicts = 4;
+}
+
+message ContentRequest {
+  string hash = 1;
+}
+
+message ContentResponse {
+  string hash = 1;
+  bytes content = 2;
+}
+