@neurodock/core 0.0.1 → 0.2.0

package/schemas/profile.example.yaml

@@ -1,112 +1,160 @@
-# NeuroDock Profile — worked example ("T" profile from plan.md §6)
+# ==============================================================================
+# WELCOME TO YOUR NEURODOCK PROFILE
+# ==============================================================================
+# Think of this as a quick instruction manual to teach the app how your brain works.
 #
-# This file is the template copied to ~/.neurodock/profile.yaml by
-# `npx neurodock init`. Every block except `identity` is optional and
-# falls back to the safe defaults documented in profile.schema.json.
+# TIPS FOR FILLING THIS OUT:
+# - Take your time. You don't have to finish it all at once.
+# - Almost everything is OPTIONAL. If you aren't sure, just leave it as is.
+# - Your data is safe. Nothing leaves your computer without your permission.
+# - You can always come back and change these later. You can't break anything.
 #
-# Loader precedence (highest wins):
-#   1. $NEURODOCK_PROFILE_PATH               (testing override)
-#   2. $XDG_CONFIG_HOME/neurodock/profile.yaml
-#   3. ~/.neurodock/profile.yaml             (default)
-#   4. ./profile.yaml                        (project-local override)
+# Where does this file live?
+#   ~/.neurodock/profile.yaml   (your machine, your private copy)
 #
-# Forward-compatibility: unknown keys at any level are preserved by
-# loaders, not stripped. A v0.1.0 install can round-trip a v0.2.0
-# profile without data loss. Run `neurodock profile validate` to catch
-# typos that permissive parsing would otherwise swallow.
-
-# Optional. Declares which schema version this file targets. Loaders
-# accept any version; they only warn when the file is newer than they
-# understand.
+# How to check it's valid after editing:
+#   neurodock profile validate
+# ==============================================================================
+
+# Leave this exactly as "0.1.0". It just helps the app read this file.
 schema_version: "0.1.0"
 
-# Required. Self-declared identity. No PII is required.
+# ------------------------------------------------------------------------------
+# 1. WHO YOU ARE (Required)
+# ------------------------------------------------------------------------------
 identity:
-  # How NeuroDock addresses you. Free-form; one letter is fine.
+  # What should we call you? A nickname or even just a single letter is totally fine.
   display_name: "T"
 
-  # Self-identified neurotypes. Self-ID is sufficient — diagnosis is
-  # never required and is never used to gate features. Skills targeted
-  # at a neurotype activate when the tag appears here.
+  # Which of these describe you?
+  # Self-ID is enough — you do NOT need a diagnosis to use any feature.
+  # Skills targeted at a neurotype activate when the tag appears here.
   # Allowed: adhd | asd | audhd | ocd | dyslexia | dyspraxia | tourette | other
   neurotypes:
     - "adhd"
     - "asd"
 
-  # Optional free-form notes. Surfaced only when a skill explicitly
-  # asks; never logged or transmitted.
+  # Is there anything else you want the app to know about how to talk to you?
+  # (For example: "I get overwhelmed by long paragraphs" or "Please be direct".)
+  # Only surfaced when a skill explicitly asks; never logged or transmitted.
   # additional_notes: "sensory-sensitive to motion; prefers terse output"
 
-# Optional. Output and reading preferences.
+# ------------------------------------------------------------------------------
+# 2. HOW YOU LIKE TO READ & WORK (Optional)
+# ------------------------------------------------------------------------------
 preferences:
-  # answer_first | conventional | bullet_first  (default: answer_first)
+  # How do you want the AI to structure its answers?
+  # Options:
+  #   answer_first  — verdict first, reasoning after. Good for ADHD triage.
+  #   conventional  — explanation first, then verdict.
+  #   bullet_first  — verdict as a bullet list.
   output_format: "answer_first"
 
-  # Max items in any list/group/step sequence. 1..20. Default 7
-  # (Miller's-number neighbourhood); 5 is the ADHD-tuned manifesto value.
+  # Max items shown in any list / group / step sequence.
+  # Range 1..20. Default 7 (Miller's number).
+  # 5 is the ADHD-tuned manifesto value — change to your comfort.
   max_chunk_size: 5
 
-  # atkinson_hyperlegible | lexend | system_default
-  # Default: atkinson_hyperlegible (evidence-based for dyslexia).
-  # 'lexend' is evidence-based for ADHD readability.
+  # Which font style is easiest for your eyes?
+  # Options:
+  #   atkinson_hyperlegible  — evidence-based for dyslexia (default)
+  #   lexend                  — evidence-based for ADHD readability
+  #   system_default          — your OS choice
   reading_font_hint: "atkinson_hyperlegible"
 
-  # reduced | system | full  (default: reduced)
-  # 'reduced' disables animation/transitions; 'system' follows the OS
-  # prefers-reduced-motion setting.
+  # How much space do you want between lines of text?
+  # This is a hint for apps that show NeuroDock's output as styled text.
+  # Options:
+  #   compact  — lines sit closer together (more text fits on screen)
+  #   default  — the app's own everyday spacing
+  #   relaxed  — extra space between lines; pairs with atkinson_hyperlegible
+  # Leave it out and the app just uses its own spacing.
+  line_height_hint: "relaxed"
+
+  # Do you want visual animations turned on?
+  # Options:
+  #   reduced  — no animations (default; safest for vestibular sensitivity)
+  #   system   — match your OS prefers-reduced-motion setting
+  #   full     — animations on
   motion: "reduced"
 
-# Optional. Thresholds consumed by mcp-chronometric.
+# ------------------------------------------------------------------------------
+# 3. TIME & FOCUS ALERTS (Optional)
+# ------------------------------------------------------------------------------
+# Helps if you tend to hyperfocus or lose track of time.
 chronometric:
-  # Continuous-session length, in minutes, at which the hyperfocus
-  # nudge fires. 15..240. Default 90. The 60/+30/+60 escalation ladder
-  # shape itself is fixed in v0.1.0; this only re-anchors the 'nudge' rung.
+  # How many minutes of straight work before we gently remind you to take a break?
+  # Range 15..240. Default 90.
+  # The 60/+30/+60 escalation ladder shape itself is fixed; this only
+  # re-anchors the 'nudge' rung in the ladder.
   hyperfocus_break_minutes: 90
 
-  # Optional. Your self-declared end-of-day time, local clock, 24h.
-  # When present, the hyperfocus monitor uses this for the
-  # "after end_of_day" nudge.
+  # What time do you want to officially "clock out" for the day?
+  # 24-hour clock (e.g. "18:30" for 6:30 PM, "22:00" for 10 PM).
+  # When set, the hyperfocus nudge gets stricter after this time.
   end_of_day_local: "18:30"
 
-  # Optional override of the energy_zone clock-band heuristic from
-  # ADR 0001. Omit unless you want to redraw your own bands.
+  # (Advanced) Re-draw your personal energy bands during the day.
+  # Leave commented out unless you specifically want to override
+  # the default clock-band heuristic.
   # zones:
   #   morning_peak: "06:00-10:30"
   #   afternoon_dip: "14:00-16:00"
 
-  # auto_close | error  (default: auto_close)
-  # What mark_session_start does when a prior session is still open.
-  # 'auto_close' is charitable to forgotten sessions; the closed
-  # session metadata is returned so the skill can surface it.
+  # What should the app do if you start a new work session but forgot
+  # to close your last one?
+  # Options:
+  #   auto_close  — safely closes the old one for you (default, charitable)
+  #   error       — stops and tells you the old session is still open
   session_overlap_policy: "auto_close"
 
-# Optional. Thresholds for mcp-guardrail detectors. Heuristics are
-# public and auditable per ETHICS; detection never blocks silently.
+# ------------------------------------------------------------------------------
+# 4. GENTLE NUDGES (Optional)
+# ------------------------------------------------------------------------------
+# Helps the app notice if you are getting stuck in a loop or overthinking.
+# Heuristics are public and auditable in ETHICS.md; detection never blocks
+# silently.
 guardrails:
-  # Number of semantically-equivalent queries in the window that
-  # triggers the rumination signal. 1..20. Default 3.
+  # How many semantically-similar questions in the window before we gently
+  # check in on you?
+  # Range 1..20. Default 3.
   rumination_threshold: 3
 
-  # Rolling window in minutes for rumination counting. 5..1440.
-  # Default 90.
+  # Over how many minutes do we count those repeated questions?
+  # Range 5..1440. Default 90.
   rumination_window_minutes: 90
 
-  # off | warn | refuse  (default: warn)
+  # Should we warn you if the AI is just agreeing with you too much instead
+  # of being helpful?
+  # Options:
+  #   off     — never flag sycophancy
+  #   warn    — flag it, you decide (default)
+  #   refuse  — refuse to send the over-validating draft
   sycophancy_check: "warn"
 
-# Optional. Consent and data-flow. Defaults are local-first; nothing
-# leaves your machine without an explicit opt-in here.
+# ------------------------------------------------------------------------------
+# 5. PRIVACY (Optional)
+# ------------------------------------------------------------------------------
+# You are in complete control. By default, everything stays on your computer.
 privacy:
-  # local | cloud_voyage | cloud_openai  (default: local)
-  # Cloud options trigger a visible "cloud embeddings enabled" notice
-  # at session start.
+  # Where should the cognitive-graph compute embeddings (for fuzzy recall)?
+  # Options:
+  #   local         — on your machine (default; uses fastembed)
+  #   cloud_voyage  — Voyage AI (opt-in; triggers a visible "cloud" notice)
+  #   cloud_openai  — OpenAI embeddings (opt-in)
   embeddings: "local"
 
-  # off | local_otel_only | full  (default: off)
-  # 'full' is reserved in v0.1.0; do not use until a future ADR lands.
+  # Do you want to send anonymous crash/bug reports to help improve the app?
+  # Options:
+  #   off              — nothing collected (default)
+  #   local_otel_only  — local-only OpenTelemetry traces; nothing leaves
+  #   full             — reserved for a future ADR; do not use yet
   telemetry: "off"
 
-  # Consent for mcp-chronometric.idle_status to read OS idle time.
-  # When false (default), idle_status returns consent_granted=false
-  # and hyperfocus_signal=unknown without error.
+  # Can the app check if your computer mouse/keyboard has been completely
+  # still? This helps it automatically pause your focus timers if you walk
+  # away from your desk.
+  # Options:
+  #   false  — no (default; idle_status returns consent_granted=false)
+  #   true   — yes, share OS idle time with the chronometric server
   os_idle_consent: false

package/schemas/profile.minimal.yaml

@@ -1,10 +1,11 @@
-# NeuroDock Profile — minimal valid example.
+# ==============================================================================
+# YOUR NEURODOCK PROFILE — minimal starter
+# ==============================================================================
+# This is the smallest valid profile. The app fills in safe defaults for
+# everything else. Open profile.example.yaml if you want to see all the
+# knobs you CAN tune.
 #
-# Only `identity` is required. Every other top-level block is optional
-# and falls back to safe, lived-experience-led defaults applied by the
-# loader (see profile.schema.json for the per-field default).
-#
-# Defaults applied when the rest of this file is omitted:
+# Safe defaults applied when you leave the other blocks out:
 #   preferences.output_format        = "answer_first"
 #   preferences.max_chunk_size       = 7
 #   preferences.reading_font_hint    = "atkinson_hyperlegible"
@@ -17,10 +18,17 @@
 #   privacy.embeddings                    = "local"
 #   privacy.telemetry                     = "off"
 #   privacy.os_idle_consent               = false
+#
+# To check it's valid after editing:  neurodock profile validate
+# ==============================================================================
 
 identity:
+  # What should we call you? A nickname or even just a single letter is fine.
   display_name: "your-name"
+
+  # Which of these describe you?
+  # Self-ID is enough — no diagnosis required.
   # Any subset of: adhd | asd | audhd | ocd | dyslexia | dyspraxia | tourette | other
-  # Empty list ([]) is valid and opts out of neurotype-tagged skill activation.
+  # An empty list [] is valid and opts out of neurotype-tagged skill activation.
   neurotypes:
     - "adhd"

package/schemas/profile.schema.json

@@ -90,6 +90,17 @@
           "enum": ["reduced", "system", "full"],
           "default": "reduced",
           "description": "Animation policy hint. 'reduced' = no animation, no transitions, no auto-scroll (default). 'system' = follow the OS prefers-reduced-motion setting. 'full' = animations allowed."
+        },
+        "line_height_hint": {
+          "type": "string",
+          "enum": ["compact", "default", "relaxed"],
+          "description": "Optional (added v0.1.x per ADR 0011). Line-height hint for any client that renders NeuroDock output as HTML or rich text, sitting alongside 'reading_font_hint'. A categorical band rather than a raw multiplier so each client maps it to its own CSS line-height. CONFORMANCE FLOOR: clients MUST NOT render body-paragraph line spacing below 1.5 regardless of band (WCAG 1.4.8 Visual Presentation / 1.4.12 Text Spacing). The bands are advisory line-height ratios relative to font size for body paragraphs; headings and other non-body text MAY be tighter. Per-band anchors: 'compact' ≈ 1.5 — the floor itself, a power-user opt-in for more text per viewport that still respects the 1.5 minimum (for readers who find generous spacing scatters their eye-line and prefer denser text, the dual of why 'relaxed' exists); 'default' ≈ 1.5–1.6 — the client's own comfortable default within the conformant range; 'relaxed' ≈ 1.65–1.8 — generous line spacing (~1.65 is the project body line-height) and the evidence-based pairing with 'atkinson_hyperlegible' for dyslexia, which is why dyslexia-aware presets set it. Read-when-present, neutral-when-absent: an untailored client ignores it; absence is NOT an error. The loader applies no value when absent. Self-ID never gates this (ADR 0004/0011).",
+          "examples": ["relaxed", "default"]
+        },
+        "voice_input_preferred": {
+          "type": "boolean",
+          "description": "Optional (added v0.1.x per ADR 0011). When true, the user predominantly dictates rather than types for sustained work (common for dyspraxic users). Downstream skills that emit code or structured text MUST NOT assume the user can hand-edit fiddly punctuation cheaply: keep examples copy-pasteable as a single block rather than scattered across inline edits. Read by the shaping layer; absence means 'no preference' and is the same as today's behaviour. Consumer pending; schema-only in this release.",
+          "examples": [true]
         }
       }
     },
@@ -121,6 +132,62 @@
           "enum": ["auto_close", "error"],
           "default": "auto_close",
           "description": "Behaviour of mark_session_start when a prior session is still open. 'auto_close' (default, charitable) closes the prior session and returns its metadata so the skill can surface it. 'error' refuses to start a new session until the prior one is explicitly closed. See ADR 0001, open question 3."
+        },
+        "calendar_phase": {
+          "type": "string",
+          "enum": ["teaching", "marking", "exam", "deadlines", "break"],
+          "description": "Optional (added v0.1.x per ADR 0011). Self-declared phase of the user's term/semester so skills can shift defaults across the calendar: tighter break cadence during 'marking' / 'exam', deadline-cluster awareness during 'deadlines' (e.g. week 12), looser during 'break'. Surfaced by the educator-semester and student-university presets. The neurotype is never a branch point (ADR 0004/0011); this is a user input the shaping layer reads, neutral-when-absent. Consumer pending (mcp-chronometric); schema-only in this release.",
+          "examples": ["teaching", "marking"]
+        },
+        "weekday_overrides": {
+          "type": "object",
+          "description": "Optional (added v0.1.x per ADR 0011). Per-weekday overrides for 'end_of_day_local' and 'hyperfocus_break_minutes', covering late-office-hours, Wednesday-afternoon-class, and library-day-vs-lecture-day patterns without forcing a whole-profile swap. Keys are lowercase English weekday names; only the seven weekdays are accepted (a misspelt key is a silent no-op, so unknown keys are rejected here rather than preserved). Each value is an override object reusing the same patterns/ranges as the top-level chronometric fields; an empty override object is valid. A weekday absent from the map inherits the top-level chronometric values. Consumer pending (mcp-chronometric); schema-only in this release.",
+          "additionalProperties": false,
+          "properties": {
+            "monday": { "$ref": "#/$defs/weekdayOverride" },
+            "tuesday": { "$ref": "#/$defs/weekdayOverride" },
+            "wednesday": { "$ref": "#/$defs/weekdayOverride" },
+            "thursday": { "$ref": "#/$defs/weekdayOverride" },
+            "friday": { "$ref": "#/$defs/weekdayOverride" },
+            "saturday": { "$ref": "#/$defs/weekdayOverride" },
+            "sunday": { "$ref": "#/$defs/weekdayOverride" }
+          },
+          "examples": [
+            {
+              "wednesday": { "end_of_day_local": "18:30" },
+              "saturday": { "hyperfocus_break_minutes": 120 }
+            }
+          ]
+        },
+        "protected_windows": {
+          "type": "array",
+          "description": "Optional (added v0.1.x per ADR 0011). Local-time ranges (lunch, post-EOD evening, scheduled lectures, lab times) where the hyperfocus monitor should HARD-SURFACE rather than nudge — the strict rung of the escalation ladder, applied because the window itself is protected, not because a session has run long. Each entry is a 'HH:MM'-'HH:MM' range with an optional human label; ranges are interpreted in the user's local timezone and a range whose 'end' is earlier than its 'start' is treated as wrapping past midnight by the consumer. An empty list is valid. Consumer pending (mcp-chronometric); schema-only in this release.",
+          "items": { "$ref": "#/$defs/protectedWindow" },
+          "examples": [
+            [
+              { "start": "12:00", "end": "12:30", "label": "lunch" },
+              { "start": "17:00", "end": "23:59", "label": "evening" }
+            ]
+          ]
+        },
+        "deadline_cluster_awareness": {
+          "type": "boolean",
+          "description": "Optional (added v0.1.x per ADR 0011). When true, planning skills surface deadline proximity and shift the break-cadence math when work clusters (e.g. three assignments due in a single week). Set by the student-university preset. Read by planning skills; absence means today's behaviour (no clustering adjustment). Consumer pending (task-fractionator); schema-only in this release.",
+          "examples": [true]
+        },
+        "time_buffer_multiplier": {
+          "type": "number",
+          "minimum": 1.0,
+          "maximum": 3.0,
+          "default": 1.0,
+          "description": "Optional (added v0.1.x per ADR 0011). Multiplier that pads presented time estimates because real-world execution time for motor-heavy tasks is systematically underestimated (e.g. 1.3 = +30%, the value the dyspraxia preset sets). Range 1.0..3.0; the neutral default 1.0 reproduces today's unpadded behaviour so an untouched profile is unchanged. Read by planning skills to scale the estimates they present; the underlying estimate is not altered. Consumer pending (task-fractionator); schema-only in this release.",
+          "examples": [1.0, 1.3]
+        },
+        "motor_fatigue_aware": {
+          "type": "boolean",
+          "default": false,
+          "description": "Optional (added v0.1.x per ADR 0011). When true, the hyperfocus monitor weights motor activity (click / keystroke / window-switch volume) into the fatigue signal rather than relying on continuous-session length alone — cognitive sharpness and motor exhaustion can coexist (set by the dyspraxia preset). The neutral default false reproduces today's session-length-only behaviour. Reading motor activity is still gated by 'privacy.os_idle_consent' and the relevant OS-input consents; this flag only declares the preference. Consumer pending (mcp-chronometric); schema-only in this release.",
+          "examples": [true]
         }
       }
     },
@@ -176,6 +243,55 @@
       }
     }
   },
+  "$defs": {
+    "weekdayOverride": {
+      "type": "object",
+      "description": "Per-weekday override for the chronometric fields that vary by day. Both members are optional and reuse the same validation as their top-level counterparts; an empty object means 'this weekday is named but inherits the top-level values'. additionalProperties is false because an unknown key here is almost always a typo that would silently do nothing.",
+      "additionalProperties": false,
+      "properties": {
+        "end_of_day_local": {
+          "type": "string",
+          "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$",
+          "description": "Override of 'chronometric.end_of_day_local' for this weekday, as 'HH:MM' (24h) in the user's local timezone. Same pattern as the top-level field.",
+          "examples": ["17:00", "18:30"]
+        },
+        "hyperfocus_break_minutes": {
+          "type": "integer",
+          "minimum": 15,
+          "maximum": 240,
+          "description": "Override of 'chronometric.hyperfocus_break_minutes' for this weekday. Same 15..240 range as the top-level field; re-anchors the 'nudge' rung for this day only.",
+          "examples": [60, 120]
+        }
+      }
+    },
+    "protectedWindow": {
+      "type": "object",
+      "description": "A single local-time range where the hyperfocus monitor hard-surfaces. 'start' and 'end' are required 'HH:MM' (24h) strings; 'label' is an optional human-readable name. additionalProperties is false to catch typos in this small, fixed shape.",
+      "additionalProperties": false,
+      "required": ["start", "end"],
+      "properties": {
+        "start": {
+          "type": "string",
+          "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$",
+          "description": "Window start, 'HH:MM' (24h), local timezone.",
+          "examples": ["12:00", "17:00"]
+        },
+        "end": {
+          "type": "string",
+          "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$",
+          "description": "Window end, 'HH:MM' (24h), local timezone. An 'end' earlier than 'start' is treated by the consumer as wrapping past midnight.",
+          "examples": ["12:30", "23:59"]
+        },
+        "label": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 80,
+          "description": "Optional human-readable label for the window, surfaced in any notice the monitor emits.",
+          "examples": ["lunch", "evening", "lecture"]
+        }
+      }
+    }
+  },
   "examples": [
     {
       "identity": {

package/src/index.test.ts

@@ -1,8 +0,0 @@
-import { describe, expect, test } from "vitest";
-import { version } from "./index";
-
-describe("@neurodock/core", () => {
-  test("exports a version constant", () => {
-    expect(version).toBe("0.0.0");
-  });
-});

package/src/index.ts

@@ -1 +0,0 @@
-export const version = "0.0.0";