chore(docs): fix markdownlint warnings across all markdown files

This commit is contained in:
Mike Kell 2026-08-10 00:03:33 -04:00
parent f596ff46cb
commit e23dce3793
11 changed files with 46 additions and 22 deletions

View File

@ -16,4 +16,3 @@
- OS keychain abstracted via `keyring` crate v3 (Windows Credential Manager / DPAPI, Linux SecretService / libsecret). Android keychain is excluded (`cfg(not(target_os = "android"))`) and will be handled by Flutter KeyStore bridge in Task 1.5. - OS keychain abstracted via `keyring` crate v3 (Windows Credential Manager / DPAPI, Linux SecretService / libsecret). Android keychain is excluded (`cfg(not(target_os = "android"))`) and will be handled by Flutter KeyStore bridge in Task 1.5.
- Raw key material is Base64-encoded before credential-store insertion for UTF-8 backend compatibility. - Raw key material is Base64-encoded before credential-store insertion for UTF-8 backend compatibility.
- Inline Base64 encode/decode helpers avoid adding an external Base64 dependency. - Inline Base64 encode/decode helpers avoid adding an external Base64 dependency.

View File

@ -1,6 +1,7 @@
# Security & Cryptography Specification # Security & Cryptography Specification
## 1. Master Key Derivation & Credential Management ## 1. Master Key Derivation & Credential Management
- **Key Derivation Function**: Argon2id - **Key Derivation Function**: Argon2id
- Memory: 64 MB (65536 KiB) - Memory: 64 MB (65536 KiB)
- Time Cost / Iterations: 3 - Time Cost / Iterations: 3
@ -12,12 +13,14 @@
- **Android**: Generated inside Android KeyStore backed by Hardware-backed Trusted Execution Environment (TEE) / StrongBox. - **Android**: Generated inside Android KeyStore backed by Hardware-backed Trusted Execution Environment (TEE) / StrongBox.
## 2. Local Database Encryption ## 2. Local Database Encryption
- **Engine**: SQLCipher 4.x - **Engine**: SQLCipher 4.x
- **Cipher Algorithm**: AES-256-CBC - **Cipher Algorithm**: AES-256-CBC
- **Key Derivation**: PBKDF2-HMAC-SHA512 (256,000 iterations default for SQLCipher 4). - **Key Derivation**: PBKDF2-HMAC-SHA512 (256,000 iterations default for SQLCipher 4).
- **Page Authentication**: HMAC-SHA512 per page. - **Page Authentication**: HMAC-SHA512 per page.
## 3. P2P Mesh Network Encryption ## 3. P2P Mesh Network Encryption
- **Transport Security Protocol**: Noise Protocol Framework (Noise_XK_25519_ChaChaPoly_BLAKE2s). - **Transport Security Protocol**: Noise Protocol Framework (Noise_XK_25519_ChaChaPoly_BLAKE2s).
- **Authentication**: Pre-shared 256-bit **Swarm Key** combined with Ed25519 node identity keys. - **Authentication**: Pre-shared 256-bit **Swarm Key** combined with Ed25519 node identity keys.
- **Peer Exchange Cipher**: Ephemeral Diffie-Hellman (X25519) key exchange + ChaCha20-Poly1305 AEAD payload ciphering. - **Peer Exchange Cipher**: Ephemeral Diffie-Hellman (X25519) key exchange + ChaCha20-Poly1305 AEAD payload ciphering.

View File

@ -1,10 +1,12 @@
# CRDT Synchronization Protocol Specification # CRDT Synchronization Protocol Specification
## 1. Core Synchronization Engine ## 1. Core Synchronization Engine
- **Framework**: Automerge (Rust Crate) - **Framework**: Automerge (Rust Crate)
- **Clock Specification**: Hybrid Logical Clocks (HLC) combining physical system time with explicit logical sequence counters to prevent clock-skew anomalies across cross-platform endpoints. - **Clock Specification**: Hybrid Logical Clocks (HLC) combining physical system time with explicit logical sequence counters to prevent clock-skew anomalies across cross-platform endpoints.
## 2. Register Models & Conflict Resolution ## 2. Register Models & Conflict Resolution
- **Task & Note Primitive Fields**: - **Task & Note Primitive Fields**:
- Properties (Title, Status, Priority Rating, Markdown Body) utilize Last-Write-Wins Element-Set (LWW-Element-Set) registers. - Properties (Title, Status, Priority Rating, Markdown Body) utilize Last-Write-Wins Element-Set (LWW-Element-Set) registers.
- Conflicts resolve deterministically based on HLC timestamps (hlc_timestamp). - Conflicts resolve deterministically based on HLC timestamps (hlc_timestamp).
@ -12,6 +14,7 @@
- Sequence Ordering uses Fractional Indexing combined with Tree-CRDT rules to eliminate circular references when moving projects offline. - Sequence Ordering uses Fractional Indexing combined with Tree-CRDT rules to eliminate circular references when moving projects offline.
## 3. Delta Exchange & Wire Protocol ## 3. Delta Exchange & Wire Protocol
- **Transport Layer**: libp2p over QUIC with direct UDP transport. - **Transport Layer**: libp2p over QUIC with direct UDP transport.
- **Delta Sync Workflow**: - **Delta Sync Workflow**:
1. Connection established via Noise XK handshake. 1. Connection established via Noise XK handshake.

View File

@ -5,15 +5,19 @@
* **Deciders**: Michael Kell * **Deciders**: Michael Kell
## Context & Problem Statement ## Context & Problem Statement
[Describe the technical context and what decision needs to be made.] [Describe the technical context and what decision needs to be made.]
## Options Considered ## Options Considered
1. [Option 1] 1. [Option 1]
2. [Option 2] 2. [Option 2]
## Decision Outcome ## Decision Outcome
Chosen Option: [Selected Option] because [justification]. Chosen Option: [Selected Option] because [justification].
## Consequences & Trade-offs ## Consequences & Trade-offs
* **Positive**: [Benefit] * **Positive**: [Benefit]
* **Negative**: [Drawback/Risk] * **Negative**: [Drawback/Risk]

View File

@ -7,6 +7,7 @@
## Context & Problem Statement ## Context & Problem Statement
Task 1.2 requires implementing a `chronogrid_crypto` crate that provides: Task 1.2 requires implementing a `chronogrid_crypto` crate that provides:
1. A master-key derivation function using Argon2id with parameters mandated by `docs/ARCHITECTURE/02-security-and-crypto.md`. 1. A master-key derivation function using Argon2id with parameters mandated by `docs/ARCHITECTURE/02-security-and-crypto.md`.
2. Cross-platform OS keychain bindings for secure credential persistence (Windows, Linux). Android is deferred to the Flutter KeyStore bridge. 2. Cross-platform OS keychain bindings for secure credential persistence (Windows, Linux). Android is deferred to the Flutter KeyStore bridge.
@ -17,20 +18,23 @@ Task 1.2 requires implementing a `chronogrid_crypto` crate that provides:
3. **Use `ring` or `sodiumoxide`** — neither provides Argon2id natively; would still need the `argon2` crate. 3. **Use `ring` or `sodiumoxide`** — neither provides Argon2id natively; would still need the `argon2` crate.
For keychain: For keychain:
1. **Direct Win32 / libsecret FFI** — full control, but significant per-platform maintenance burden. 1. **Direct Win32 / libsecret FFI** — full control, but significant per-platform maintenance burden.
2. **`keyring` crate** — abstracts Windows Credential Manager, Linux SecretService, and macOS Keychain behind a single API. 2. **`keyring` crate** — abstracts Windows Credential Manager, Linux SecretService, and macOS Keychain behind a single API.
## Decision Outcome ## Decision Outcome
**Chosen Options:** **Chosen Options:**
- `argon2` crate v0.5 (RustCrypto) for KDF — spec-compliant, zero-copy output, and widely audited.
- `keyring` crate v3 for cross-platform OS keychain — minimal code, covers Windows + Linux targets. Android is excluded via `cfg(not(target_os = "android"))` and will be handled by the Flutter KeyStore bridge. * `argon2` crate v0.5 (RustCrypto) for KDF — spec-compliant, zero-copy output, and widely audited.
* `keyring` crate v3 for cross-platform OS keychain — minimal code, covers Windows + Linux targets. Android is excluded via `cfg(not(target_os = "android"))` and will be handled by the Flutter KeyStore bridge.
**Key design choices:** **Key design choices:**
- Argon2id parameters: memory = 65 536 KiB (64 MiB), time_cost = 3, parallelism = 4, salt = 16 bytes, output = 32 bytes.
- `DerivedKey` struct wraps key + salt and implements `Zeroize + Drop` for automatic memory scrubbing. * Argon2id parameters: memory = 65 536 KiB (64 MiB), time_cost = 3, parallelism = 4, salt = 16 bytes, output = 32 bytes.
- `Debug` impl on `DerivedKey` redacts key material to prevent accidental log leaks. * `DerivedKey` struct wraps key + salt and implements `Zeroize + Drop` for automatic memory scrubbing.
- Raw bytes are Base64-encoded before keychain insertion for UTF-8 credential backend compatibility, using inline encode/decode helpers (no extra dependency). * `Debug` impl on `DerivedKey` redacts key material to prevent accidental log leaks.
* Raw bytes are Base64-encoded before keychain insertion for UTF-8 credential backend compatibility, using inline encode/decode helpers (no extra dependency).
## Consequences & Trade-offs ## Consequences & Trade-offs

View File

@ -6,4 +6,4 @@
- [x] **Task 1.2**: Implement chronogrid_crypto crate with Argon2id master key derivation and OS keychain bindings. - [x] **Task 1.2**: Implement chronogrid_crypto crate with Argon2id master key derivation and OS keychain bindings.
- [ ] **Task 1.3**: Implement chronogrid_core database initializers using SQLCipher 4.x matching docs/API_CONTRACTS/schema.sql. - [ ] **Task 1.3**: Implement chronogrid_core database initializers using SQLCipher 4.x matching docs/API_CONTRACTS/schema.sql.
- [ ] **Task 1.4**: Integrate Automerge Rust crate into chronogrid_core for task and note CRDT register mutations. - [ ] **Task 1.4**: Integrate Automerge Rust crate into chronogrid_core for task and note CRDT register mutations.
- [ ] **Task 1.5**: Generate lutter_rust_bridge FFI bindings bridging Rust storage methods to Dart. - [ ] **Task 1.5**: Generate lutter_rust_bridge FFI bindings bridging Rust storage methods to Dart.

View File

@ -1,16 +1,19 @@
# Eisenhower Priority Matrix View Specification # Eisenhower Priority Matrix View Specification
## 1. Urgency-Importance Scoring Formula ## 1. Urgency-Importance Scoring Formula
Tasks auto-calculate an Urgency-Importance Vector Score ($) executed locally inside Rust: Tasks auto-calculate an Urgency-Importance Vector Score ($) executed locally inside Rust:
S = (W_i * P_user) + (W_u * f(Due_Date - t_current)) + (W_a * Age) `S = (W_i * P_user) + (W_u * f(Due_Date - t_current)) + (W_a * Age)`
Where: Where:
- P_user: User-assigned priority coefficient (0.0 to 1.0). - P_user: User-assigned priority coefficient (0.0 to 1.0).
- (Δt): Proximity decay function yielding exponential values as due dates approach. - (Δt): Proximity decay function yielding exponential values as due dates approach.
- W_i, W_u, W_a: Configurable weighting coefficients for importance, urgency, and age accumulation. - W_i, W_u, W_a: Configurable weighting coefficients for importance, urgency, and age accumulation.
## 2. Quadrant Assignment Mapping ## 2. Quadrant Assignment Mapping
- **Quadrant I (Do First - Urgent & Important)**: Score >= Threshold_High AND Due_Date <= 48 Hours. - **Quadrant I (Do First - Urgent & Important)**: Score >= Threshold_High AND Due_Date <= 48 Hours.
- **Quadrant II (Schedule - Not Urgent & Important)**: Score >= Threshold_High AND (Due_Date > 48 Hours OR Due_Date IS NULL). - **Quadrant II (Schedule - Not Urgent & Important)**: Score >= Threshold_High AND (Due_Date > 48 Hours OR Due_Date IS NULL).
- **Quadrant III (Delegate/Automate - Urgent & Not Important)**: Score < Threshold_High AND Due_Date <= 48 Hours. - **Quadrant III (Delegate/Automate - Urgent & Not Important)**: Score < Threshold_High AND Due_Date <= 48 Hours.

View File

@ -1,9 +1,11 @@
# Calendar & Time-Blocking Grid Specification # Calendar & Time-Blocking Grid Specification
## 1. Display Interface ## 1. Display Interface
- Multi-day, Weekly, and Monthly time-blocking grids rendered via Flutter custom painter. - Multi-day, Weekly, and Monthly time-blocking grids rendered via Flutter custom painter.
- Drag-and-drop task placement: Dragging an unscheduled task onto the grid automatically updates its due_date timestamp and reserves a dedicated block based on its stimated_duration. - Drag-and-drop task placement: Dragging an unscheduled task onto the grid automatically updates its due_date timestamp and reserves a dedicated block based on its stimated_duration.
## 2. Local CalDAV Bridge Protocol ## 2. Local CalDAV Bridge Protocol
- **Local Endpoint**: Embedded HTTPS/CalDAV service running locally on 127.0.0.1:4242. - **Local Endpoint**: Embedded HTTPS/CalDAV service running locally on 127.0.0.1:4242.
- **Interoperability**: Allows native OS calendar tools (Outlook, Thunderbird, Android DAVx⁵) to read scheduled task blocks directly as standard calendar events without sending data to external cloud servers. - **Interoperability**: Allows native OS calendar tools (Outlook, Thunderbird, Android DAVx⁵) to read scheduled task blocks directly as standard calendar events without sending data to external cloud servers.

View File

@ -1,11 +1,13 @@
# Kanban & Gantt Multi-Project View Specification # Kanban & Gantt Multi-Project View Specification
## 1. Multi-Level Kanban Board ## 1. Multi-Level Kanban Board
- Columns represent task status (acklog, in_progress, eview, completed).
- Horizontal swimlanes group tasks by - Columns represent task status (acklog, in_progress, eview, completed).
amespace_id or project_id. - Horizontal swimlanes group tasks by
- Dragging a card between columns updates its status field, triggering a CRDT state emission across active peers. amespace_id or project_id.
- Dragging a card between columns updates its status field, triggering a CRDT state emission across active peers.
## 2. Interactive Gantt Timeline
- Visualizes project milestones, task dependencies, and critical path progression. ## 2. Interactive Gantt Timeline
- Supports fractional sub-project rendering, allowing infinite sub-task nesting.
- Visualizes project milestones, task dependencies, and critical path progression.
- Supports fractional sub-project rendering, allowing infinite sub-task nesting.

View File

@ -1,6 +1,7 @@
# Master User Story: Distributed, Local-First Productivity Engine # Master User Story: Distributed, Local-First Productivity Engine
Refer to Master User Story specification for detailed acceptance criteria regarding: Refer to Master User Story specification for detailed acceptance criteria regarding:
1. Multi-domain IMAP ingestion and local file watchers. 1. Multi-domain IMAP ingestion and local file watchers.
2. Serverless P2P CRDT sync across Windows, Linux, Android, and Headless nodes. 2. Serverless P2P CRDT sync across Windows, Linux, Android, and Headless nodes.
3. Multi-view display execution (Eisenhower Matrix, Time-Blocking Calendar, Kanban, Notes). 3. Multi-view display execution (Eisenhower Matrix, Time-Blocking Calendar, Kanban, Notes).

View File

@ -1,16 +1,19 @@
# Ingestion & Local Automation Pipeline # Ingestion & Local Automation Pipeline
## 1. Direct TLS IMAP Engine ## 1. Direct TLS IMAP Engine
- Embedded within crates/chronogrid_core (Rust native). - Embedded within crates/chronogrid_core (Rust native).
- Connects directly over TLS to user-configured mailboxes (Personal Gmail, M365 Exchange, Custom IMAP). - Connects directly over TLS to user-configured mailboxes (Personal Gmail, M365 Exchange, Custom IMAP).
- Polls for flagged emails or direct forwards to internal local parse addresses. - Polls for flagged emails or direct forwards to internal local parse addresses.
- Extracts message body to Markdown, preserves message thread headers (In-Reply-To, Message-ID), and creates linked tasks. - Extracts message body to Markdown, preserves message thread headers (In-Reply-To, Message-ID), and creates linked tasks.
## 2. Native Quick Jots & Trigger Integrations ## 2. Native Quick Jots & Trigger Integrations
- **Windows / Linux**: System-wide global hotkey listener invokes a lightweight FFI command overlay. - **Windows / Linux**: System-wide global hotkey listener invokes a lightweight FFI command overlay.
- **Android**: Home-screen widget and Share-Intent listener push text, links, or audio payloads directly to the local ingestion buffer. - **Android**: Home-screen widget and Share-Intent listener push text, links, or audio payloads directly to the local ingestion buffer.
## 3. Embedded AI Processing Architecture ## 3. Embedded AI Processing Architecture
- **Inference Engine**: Embedded ONNX Runtime / local LLM socket (Ollama). - **Inference Engine**: Embedded ONNX Runtime / local LLM socket (Ollama).
- **Parsing Pipelines**: - **Parsing Pipelines**:
1. **Namespace Classifier**: Determines destination space (Personal, Engineering, Creations). 1. **Namespace Classifier**: Determines destination space (Personal, Engineering, Creations).