🔮  Lucid

A local-first personal operating system
with the Mirror that understands you and the Engine that keeps you moving, over one Ledger you own.

Nobody handed you an instruction manual. You got a body that hurts in ways you can't explain in a fifteen-minute appointment. Patterns you've sworn off every January since you can remember. Insights that arrive in the shower and dissolve by breakfast. A story about yourself that quietly rewrites its own history every time you fall short. And everyone you know is carrying some version of the same thing — we all hurt, we all repeat, we all forget. We just don't keep records.

Imagine waking up and knowing exactly what's been weighing on you—not vaguely, but precisely. You've mentioned feeling "not enough" four times this week. The system noticed. It connects this to a wound you identified months ago and asks: Does this resonate? It never says you are — it asks does this fit? You're the only authority on you; Lucid just never loses the evidence.

Imagine your body finally having a biographer. One-line logs — pain, meals, sleep, a mood, a memory that surfaced — and the world's half filled in around them: the weather that day, where you were. Eighteen months later you walk into an appointment carrying the record no doctor has time to take: every flare, everything you tried, what actually helped. Your suspicion that the pressure drop wrecks your knee? Finally checkable, against your own data. The hard days stop being merely endured — they become the most informative entries in the set.

Your friend's birthday is approaching. A message is already drafted—it mentions the trip you took together last year, the inside joke about coffee. It sounds like you, because it learned how you express care. You review it, change a word, send it. The intention was always yours; the system just cleared the friction. This is what it looks like when the people you love get the best of you — instead of whatever was left of you.

And the past isn't as gone as it feels. Most of your life was never lost — it's unindexed. Give the system one fragment a week — the house you grew up in, the year everything changed — and watch what comes back within reach: places you haven't thought about in twenty years, the exact moment a pattern was born. You will remember more than you believe you can. And this time it stays remembered, in your own words, no longer at the mercy of the story your mind keeps revising. Not a therapist you see once a week. Not a journal you forget to write in. Something that holds your whole story across time — and asks the questions you didn't know you needed to hear.

Now the honest part. You've tried systems before. There's a graveyard of them behind you, and every headstone reads the same: day twelve, the first miss, the shame about missing, the quiet uninstall. Lucid was built from studying exactly that failure.

On your worst day, the practice costs one sentence. That's the floor, and there is nothing beneath it. Miss a day and all you get is the smallest nudge — never makeup work to catch up on. Nothing you write is ever scored, and coming back after a long silence is met with welcome, not a reckoning.

And yet the pressure is real. At 9:30 tonight a bell rings, because insight you never act on is just a more articulate way of staying stuck. There's a witness. There's something at stake. There's a record that a bad week can't quietly rewrite. But that accountability only ever touches whether you showed up — never what you said when you did.

The side of Lucid that understands you never pushes. The side that pushes you never reads a word of what you wrote. That line between them is the whole design — and it's why this is the one that survives you.

Ten years from now, there are two versions of you. One has a decade of evidence: every pattern named and tested against reality, a body mapped against weather and sleep and everything it was fed, the recovered memories, the receipts of who they became. Every year the tools get smarter, and they amplify whatever you hand them — and only you can hand them you. The other version is still making the January promise, from memory. Same person. Same pain. The only difference is that one of them kept the record.

We were all born without the manual.

This is how you write yours. This is Lucid.

The first entry is one line. The bell rings at 9:30.

---

Project Navigation

🚀 Installation	🗺️ Command Reference	⚡ Quick Start
🧭 Architecture	📚 Documentation	🔐 Security
🛠️ Code Standards	🤖 AI Usage	🧪 Examples & Tests
🤝 Contributing	👥 Maintainers	⚖️ License

Project Status

CI / CD		Quality
Security		Community

Lucid is a single Go binary with two cooperating subsystems over one shared, user-owned record. The Mirror captures the life stream and reflects it back — capture, patterns, self-understanding — and never enforces. The Engine defends the small set of committed daily practices — bell, chain, floor, witness, escalation — and never reads a word of what you wrote. Both write one append-only Ledger of plain files under ~/.lucid/, which talks to no cloud service.

The whole design is the line between those two halves: the side that understands you never pushes; the side that pushes you never reads content. Reflection tools fail without a behavior layer, and behavior tools fail without a reflection layer — Lucid is deliberately both, with a hard boundary between what each is allowed to do.

                             one act — a two-minute nightly close-out —
                                     feeds both subsystems
                                              │
                 ┌────────────────────────────┴─────────────────────────────┐
                 ▼                                                          ▼
     ┌───────────────────────────┐                       ┌───────────────────────────┐
     │  MIRROR                   │  ──── never reads ───▶│  ENGINE                   │
     │  understands you          │                       │  keeps you moving         │
     │  capture · patterns       │◀─── never scores ─────│  bell · chain · floor     │
     │  reflection · recall      │       what you say    │  witness · escalation     │
     │  (never enforces)         │                       │  (never reads content)    │
     └─────────────┬─────────────┘                       └─────────────┬─────────────┘
                   │                                                   │
                   └──────────────────────────┬────────────────────────┘
                                              ▼
                          ┌────────────────────────────────────┐
                          │  LEDGER — append-only, plain files │
                          │  yours, offline (~/.lucid/)        │
                          └────────────────────────────────────┘

🚀 Installation

Lucid requires a supported release of Go (Go 1.26+) only if you build from source, and is built CGO_ENABLED=0 — a single static binary named lucid. It runs on macOS or Linux and stores everything under a user-owned Ledger at ~/.lucid/.

⚠️ Status: Lucid is PRE-RELEASE (pre-1.0); commands and the ~/.lucid/ layout may still change before 1.0. The whole command surface below runs today — the deterministic daily loop (capture, close-out, observations, the day view, exports) needs no model and no network, while the autonomous sends (bell, companion, witness report, workout slot) need a delivery channel and the reflective verbs need an LLM provider configured. PRs are welcome.

Install the binary

Install the latest prebuilt release into ~/.local/bin — a user‑writable directory, so no sudo, and lucid update can self‑update in place afterward.

No curl … | sudo bash here — we don't ask you to pipe a mystery script into your shell and hope for the best. Every line below is in the open, and the download is checked against the release's published SHA‑256 checksums before anything lands on your PATH:

# Install the latest lucid release into ~/.local/bin, verified against checksums.txt
VER=$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/mrz1836/lucid/releases/latest | sed 's#.*/v##')
OS=$(uname -s | tr '[:upper:]' '[:lower:]'); ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
F="lucid_${VER}_${OS}_${ARCH}.tar.gz"; U="https://github.com/mrz1836/lucid/releases/download/v${VER}"
mkdir -p ~/.local/bin && cd "$(mktemp -d)" && curl -fsSLO "$U/$F" \
  && WANT=$(curl -fsSL "$U/lucid_${VER}_checksums.txt" | awk -v f="$F" '$2==f{print $1}') \
  && GOT=$( { command -v sha256sum >/dev/null && sha256sum "$F" || shasum -a 256 "$F"; } | awk '{print $1}') \
  && [ -n "$WANT" ] && [ "$WANT" = "$GOT" ] \
  && tar -xzf "$F" -C ~/.local/bin lucid
lucid version

If lucid isn't found afterward, add ~/.local/bin to your PATH (put export PATH="$HOME/.local/bin:$PATH" in your ~/.zshrc or ~/.bashrc).

Build from source (contributors)

Requires Go 1.26+ and git.

git clone https://github.com/mrz1836/lucid.git && cd lucid
magex build          # emits ./cmd/lucid/lucid
# or, without the mage toolchain:
go build -o lucid ./cmd/lucid

Put the resulting binary on your PATH, e.g. install -m 0755 lucid ~/.local/bin/lucid.

Scaffold the Ledger

lucid init           # creates ~/.lucid/ (dirs 0700, files 0600); idempotent

You often don't even need it — most stateful commands self-scaffold on first use, so capture never blocks on setup. Override the location with LUCID_HOME=/some/path.

Keep lucid up to date

lucid update (alias lucid upgrade) downloads the latest release, verifies its SHA‑256 checksum against the published lucid_<ver>_checksums.txt, and atomically replaces the running binary — no sudo when it lives in ~/.local/bin.

lucid update            # download & install the latest release
lucid update --check    # report whether a newer version is available
lucid update --force    # reinstall the latest even if already current
lucid update --verbose  # narrate each step

Every other command also runs a passive, cached background check and prints a one‑line "a new version is available" notice. It never blocks or fails a command, is skipped for development builds, and is silenced by LUCID_NO_UPDATE_CHECK=1 (or the shared NO_UPDATE_CHECK / CI). If you hit GitHub API rate limits, a token is read from LUCID_GITHUB_TOKEN, then GITHUB_TOKEN, then GH_TOKEN.

Heads up: a binary that another installer owns — go install's ~/go/bin, or a Homebrew prefix — is refused by lucid update rather than overwritten (that would break the tool that owns it). Install the release binary into ~/.local/bin as above to keep self‑update working.

🗺️ Command reference

Every lucid command and flag, grouped by what you're doing. The daily loop is deterministic — no model, no network — so capture and the close-out never wait on a provider (P9).

Everywhere: --json is persistent on every command (commands with a structured shape emit it; the human-first ones — log, obs, mode, closeout — print prose), and -h / --help works at every level. Exit codes are stable: 0 success, 1 runtime error or breached gate, 2 usage / flag-parse error.

The daily loop

Command	Flags	What it does
log [text]	--day --source --channel --thread --agent --model --harness	Capture one immutable raw entry — no structure imposed at capture time.
obs [kind] [value…]	same as log	One-line health/context micro-log — pain, mood, sleep, place. Inventory, never obligation.
attach <path>	--caption --day --source --channel --harness --to	Attach a photo or file to a logical day — optionally linking it to what it's about at capture time (--to <kind>:<key>, repeatable).
mode <green|yellow|red>	--day	Declare today's capacity mode; the floor drops with it (rejected after the bell).
closeout [today|skip|backfill] [compact form…]	--day	The two-minute nightly close-out — record the day's committed practice. Idempotent per logical day.

Read the record

Command	Flags	What it does
day [date|yesterday]	—	The joined day view — engine record + observations + enrichment + raw entries.
status	—	Ambient Engine state: streak, adherence vs. declared mode with its honest co-numbers, error-budget burn, days to the next gate.
metrics	—	Practice-quality rollup: current/longest streak, 30-day adherence (30/60/90 gate rollups under --json), misses, error budget, days-since per anchor.
stats	--last --from --to	Ledger volume over a window of logical days — counts only, never content.
reflect [gate]	—	Recall your validated insights; never proposes a new pattern.
reflect week	--days --since --week	Read-only weekly deep-dive since your last reflection. reflect week apply persists a candidate through the resonance gate (JSON on stdin); reflect week close stamps the cursor.
ask <question…>	—	Grounded, cited Q&A across your validated insights and reflections.
recall	--era --injury --thread --pet	Browse the archive by era, thread, injury, or pet (never writes).
gallery	--since --until --to	Browse stored media as a date-ordered timeline for before/after comparison — filterable by an inclusive date window and/or one linked subject (never writes).
excavate	—	Select the next memory cluster to excavate (never writes).
person <name>	—	Look up a person you've mentioned.
person reconcile	—	List likely-duplicate people with a suggested merge — read-only, no-LLM, changes nothing.

Build your history

Command	Flags	What it does
memory <text>	--day --era --people --place --tone --why --certainty --followup --attach --caption	Record a story from your past — backdated, linked, kept.
era list era create <name> · era amend <name>	--start --end --note (on create/amend) --json	Life chapters, by subcommand: era list reads (never writes), era create mints a new chapter (the only path that does), era amend amends an existing one. A non-matching amend (or bare era <name>) hard-errors — no accidental chapters.
injury <name>	--onset --status --body-area --severity --cause --timeline --treatments --lasting-effects --current-limitations --uncertainty --note	Record or amend an injury in your body history — testimony, not a clinical scale.
thread <name>	--intent --status --domain --note	Record or amend an ongoing thread.
reframe add <catch> <flip> reframe list · reframe surface	--day (on add) --json (on list/surface)	Keep and rotate your self-talk reframes — a catch → flip pair. Append-only; surface shows one per logical day, least-recently-surfaced (idempotent within the day).
focus add <text> focus list · focus surface · focus retire <id>	--success --day (on add) --all --json (on list)	Keep and rotate your daily focus work-ons — a thing to work on, with an optional success criterion. Append-only; surface shows one active item per logical day, least-recently-surfaced (idempotent within the day); retire deactivates without deleting (audit view via list --all).
gratitude add <thing> gratitude list · gratitude merge <src> <dst> · gratitude import <thing>	--into --day --count --first --last (on add/import) --json (on list)	Keep a running gratitude tally — the count of things you return to gratitude for. Append-only registry; add canonical-key-matches and bumps or creates an entry (--into <id> bumps a specific entry when tonight's wording differs), merge folds an accidental duplicate, and import seeds an existing count with explicit first/last. Every write returns a receipt id; the verbatim nightly gratitude stays a separate lucid log.
retro park <item> retro list · retro show <R-NNN> · retro resolve <R-NNN> · retro defer <R-NNN>	--source --day (on park) --all --resolved --json (on list)	Keep the retro parking lot — the R-NNN queue of things parked to revisit at the weekly Retro or a Gate. Append-only; park mints the next global R-NNN and returns it plus a per-write receipt (the id an agent echoes back), list defaults to open and deferred (--all adds resolved), resolve records what you did without deleting (the audit trail), and defer sets a first-class deferred status that stays in the walk.
pet <name>	--species --status --start --end --note	Record or amend a companion in your pet registry — status is its own active/rehomed/passed vocabulary; --start/--end are backdate-aware, so a companion from years ago is recorded with whatever precision you remember.
self [<key-or-prefix>]	--history	Read the durable self-profile — atemporal facts under identity. body. constraint. pref. misc.
self set <key> <value…>	--note --since	Record one durable fact. Append-only: a correction is just another set.
self move <key> <new-key> self retire <key> [reason…]	—	Re-categorize a fact, or retire one that stopped being true. History carries forward; nothing is ever deleted.
person merge <source> <target> person alias <subject> <form> person rename <subject> <new-name…>	—	Reconcile the people records: fold a duplicate onto a canonical record (append-only redirect, never a delete), record another written form, or change a display name (the person_key is stable).
person set <subject>	--dob --relationship --note	Record the user-authored durable fields on a person — never inferred.
person off-limits <subject>	--restore	Mark a person off-limits to inference (the P-3 redaction); --restore clears it.
anchor add <label> <date> [note…]	—	Record a days-since milestone. A future date is accepted — an anchor may be a date you count toward.
anchor rename <label> <new-label> anchor sunset <label> [reason…]	—	Rename a milestone's display label (the day count carries forward), or retire it from the counting surfaces (the record is kept).
link <media> unlink <media> annotate <media>	--to --note	Point a stored attachment at anything it's about — a person, injury, day, anchor, thread — through the append-only link ledger (--to <kind>:<key>, repeatable). unlink retires an association; annotate adds a note to one. Correctable and retroactive; the media binary is never touched and nothing is destroyed.
structure [raw_id]	--since --until --force	Run the Structuring pass over raw entries a check-in did not capture — one id, or an inclusive date window.
bootstrap [done]	—	Toggle historical-entry mode to backfill the past without disturbing today.

Accountability & autonomous sends

Command	Flags	What it does
scheduler run	--db	The send daemon — evening bell + morning tripwire on the chain's clocks; blocks until interrupted. Deterministic and agent-free.
scheduler status	--scheduler-db --companion-db	Read-only health verdict: what fires next, what happened last, what is broken. Exits 0 ok / 1 warn / 2 error.
scheduler reconcile	--slug --no-fire --db	Re-arm a parked scheduled send — the sanctioned repair. Idempotent, and sends nothing itself.
scheduler install	--apply --out --force --lucid --hush --hush-server --machine-index --scheduler-db --supervise-config	Render and lint the supervised launchd + hush artifacts. Prints by default, --out writes them, --apply performs the host install (macOS).
scheduler uninstall	--dry-run --label	Bootout and remove the supervised launchd job (idempotent).
companion fire	--mode --deliver --dry-run	Compose one daily companion message now — --mode morning|night is required. Dry-run unless --deliver.
witness report	--deliver --dry-run	Compose the weekly witness report now. Dry-run unless --deliver.
workout	—	Compose today's training recommendation — a deterministic core decides, the model only phrases it.
workout fire	--deliver --dry-run	Compose the daily workout message now. Dry-run unless --deliver.
workout log [drop…]	--type --duration --rpe --parts --movements --soreness --pain --notes --anchor --anchor-item --text + log's capture flags	Log a completed workout — structured flags, or a spoken drop via --text.
storm <clause-label|unwritten|end>	--day	Declare, renew, or end a storm (a grace window).
profile <name>	—	Switch to a named clock profile.

System & data

Command	Flags	What it does
init	—	Scaffold the ~/.lucid/ Ledger (idempotent; most verbs also self-scaffold).
export [series | packet clinician [@date|all]]	—	Export a CSV series or a clinician packet — zero journal content by default.
backup	--out	Write the must-keep Ledger trees to a single .tar.gz. Never writes into ~/.lucid/, never clobbers an existing file.
restore [<file>]	--in --force	Overlay a backup archive back into the Ledger; refuses an occupied home without --force.
secret <add|list|note|remove>	--note --clear	Maintain a names-only catalog of hush secret handles — a handle and an optional note, never a value. note updates a live handle's note (or removes it with --clear), keeping its creation time; remove tombstones it. History stays append-only. No reveal, no fetch, no storage.
validate	—	Read-only architecture & boundary sweep (boundary, diagnostic-language, links, schema).
serve	—	Speak the stdin/JSON protocol that drives the interactive /checkin — the chat-harness entry point.
version	—	Print build metadata: version, commit, build date.
update	--check --force --verbose	Self-update in place from a GitHub release (alias: upgrade).
completion <bash|zsh|fish|powershell>	—	Emit the shell autocompletion script.

Environment

Variable	Effect
LUCID_HOME	Override the Ledger location (default ~/.lucid/).
LUCID_NO_UPDATE_CHECK	Silence the passive "a new version is available" notice (1/true); the shared NO_UPDATE_CHECK and CI also disable it.
LUCID_HARNESS_TOKEN	The chat-bot token scheduler run posts with. Injected at spawn — vaulted in hush, never committed.
LUCID_USER_CHANNEL_ID · LUCID_WITNESS_CHANNEL_ID	Real channel IDs the logical user and witness sends resolve to. Injected, never committed.
LUCID_SCHEDULER_DB · LUCID_COMPANION_DB · LUCID_WITNESS_REPORT_DB · LUCID_WORKOUT_DB	Override a disposable job-store path. All default outside ~/.lucid/ — machinery, never the record.
LUCID_SOURCE · LUCID_HARNESS · LUCID_CHANNEL · LUCID_THREAD · LUCID_AGENT · LUCID_MODEL	Default capture provenance so a relaying harness attributes an entry without repeating flags. Resolution is flag > env > default; each capture verb reads the ones it exposes as flags.

Full synopsis, examples, and error behavior for every command live in docs/usage/commands.md; the config-gated sends have their own guides (companion, witness report, workout).

💬 Chat-driven, optionally. lucid serve speaks a stdin/JSON protocol so a chat client can drive the interactive close-out. Three provider-backed Mirror verbs ride it — /checkin, /reflect, /ask — structuring entries, proposing one resonance-gated pattern, and recalling it later; the rest (/log, /closeout, /mode, /status, /day, /storm, /profile, /person, /bootstrap) are verbatim passthroughs to the CLI verbs above. Every one is also a direct command, so the CLI is fully usable standalone.

⚡ Quick Start

The whole daily rhythm is small on purpose. Here is a first pass with the verbs that work today.

lucid init                      # scaffold ~/.lucid/ (or just start logging)
lucid log "trying it out"       # your first entry — one line is the floor
lucid closeout                  # the two-minute nightly close-out
lucid status                    # streak, mode-relative adherence, error budget

🕤 The bell rings at 9:30. The Engine assumes starting is the scarce resource, not persisting. On a hard day, declare it — lucid mode red — and the floor drops to a single sentence. There is nothing beneath the floor.

🩺 Give your body a biographer. lucid obs pain 6 knee or lucid obs mood 7 logs one line, sub-second, no judgment. Then lucid day joins the whole day — engine record, observations, and entries — into one view. Observations are inventory: they never carry a streak, target, or score.

The morning/evening walkthrough, configuration, and the data-and-privacy model are in docs/usage/getting-started.md.

🧭 Architecture

Lucid is two subsystems over one substrate, with a hard boundary between them:

• Mirror — produces understanding. Captures the life stream (prose and one-line observations), maintains a longitudinal self-model, and interprets events through user-selected frameworks. It proposes; you accept, edit, or reject. It never enforces.
• Engine — produces behavior. Initiates, sequences, and defends the small set of committed daily practices, and enforces accountability for whether a practice occurred — never for its content. It reads runtime state only, never Mirror content.
• Ledger — the append-only event store, the single source of truth: plain, user-owned, exportable files under ~/.lucid/. AI is a stateless analyst over relevant excerpts, never the system of record.

What Lucid will never do

• No cloud sync, no telemetry, no analytics, no accounts — the record lives on your machine and is always exportable as a directory of plain files.
• Nothing you write is ever scored, streaked, or penalized. Consequences attach to acts (did you show up?), never to content.
• No autonomous messages beyond the pre-committed Engine templates (bell, nudge, witness escalation) and the opt-in, config-gated sends (the daily companion, the weekly witness report, and the workout slot), and no outbound fetch beyond opted-in, outbound-minimal enrichers.
• No diagnosis. The voice is a trusted advisor — warm, honest, humble about certainty — offering hypotheses, never verdicts.

The whole design in ~150 lines, including the ten principles (P1–P10) that govern both halves, is in docs/architecture.md.

📚 Documentation

Understand it

Doc	Purpose
docs/vision.md	The long-form product vision: the five roles Lucid plays, and sharing the record — the right truth, at the right depth, for the right person.
docs/architecture.md	The whole design in ~150 lines: the Mirror and the Engine over one user-owned Ledger, and the ten principles that govern both.
docs/engine.md	The half with consequences: chains, bells, floors, modes, storms, telemetry, and the accountability ladder.
docs/observations.md	The body's biographer: one-line logs on a frozen event envelope; registries, enrichers, and the projections that turn a life into a queryable record. Inventory, never obligation.
docs/frameworks.md	Interpretation lenses — Stoicism, NVC, IFS, attachment theory, Eight Dates, the Four Agreements, or any tradition you author. Your worldview is sovereign; the record stays lens-neutral forever.
docs/scientist.md	Pre-registered self-experiments at Retro/Gate cadence — and how the design learns across users while the data never leaves.
docs/calibration.md	The one doc you fill in: copy it to personal/calibration.md (private, never enters shared history) and answer its questions. Five minutes and Phase 0 is running.

Use it

Doc	Purpose
docs/usage/install.md	Get the lucid binary (from source, go install, or a release), verify it, and scaffold the ~/.lucid/ Ledger.
docs/usage/getting-started.md	The mental model, the morning/evening daily rhythm, a first-week walkthrough, configuration, and data & privacy.
docs/usage/commands.md	Every lucid CLI command and sub-form, plus the chat/harness slash commands — synopsis, flags, examples, and the shared date grammar.
docs/usage/natural-language.md	The voice-first layer: talk in plain language and let a harness map it onto the exact documented command. The CLI stays the contract.
docs/usage/weekly-reflection.md	lucid reflect week — the read-only weekly deep-dive, the window it resolves, and the resonance gate behind week apply.
docs/usage/life-archive.md	Excavating the past: the injury/body-history track and the story track, kept separate so a session opens exactly one.
docs/usage/companion.md · witness-report.md · workout.md	The three config-gated, off-by-default sends: the daily companion, the friend-facing weekly report, and the training loop.
docs/usage/harness-setup.md	Driving Lucid's deterministic loop from a chat surface — no LLM provider and no secrets inside Lucid.

Go deeper

Doc	Purpose
docs/technical-spec.md	The reference architecture for the whole system — every subsystem, record, and seam.
docs/adr/README.md	The architecture decisions of record: a Go core with a CLI-first surface, plain files with SQLite as a later index, the chat harness as thin sugar over the binary.
docs/mvp/scope.md	The canonical build scope: the unified nightly loop, its agent contracts, and its acceptance criteria on one page.
docs/mvp/README.md	The engineering doc set — data model, error states, and per-module contracts — the source of truth for how the internals fit together.

🔐 Security

Important disclaimer

⚠️ Experimental, deeply personal software — use at your own risk

Lucid is pre-release, open-source software provided "AS-IS" without warranty. By running it, you acknowledge:

• Status: pre-1.0; expect bugs, edge cases, and breaking changes to commands and the ~/.lucid/ layout.
• Your data is yours. lucid backup writes the must-keep set (raw/, media/, observations/, registries/, links/, secrets/, engine/ minus status.json, and projections/exports.log) to a single archive; lucid restore rebuilds it — the association ledger and the binaries its links point at survive together. There is still no cloud copy — the backup goes where you tell it.
• Not medical advice. Lucid is not a therapist or clinician; health projections are data for you and your care team, never a diagnosis.
• No liability. The authors accept no responsibility for lost data, downtime, or any decision made with it.

For security issues, see our Security Policy or contact lucid@mrz1818.com.

Additional documentation & repository management

Development Setup (Getting Started)

Install MAGE-X for development and building:

go install github.com/magefile/mage@latest
go install github.com/mrz1836/go-mage/magex@latest
magex update:install

Build Commands

View all build commands:

magex help

Common commands:

• magex build — build the lucid binary
• magex test — run the test suite (race + coverage)
• magex lint — run all linters (golangci-lint, 60+)
• magex format:fix — gofumpt + imports

GitHub Workflows

Lucid uses the GoFortress workflow system for comprehensive CI/CD:

• fortress-test-suite.yml — the Go test suite across versions
• fortress-code-quality.yml — gofmt, golangci-lint, staticcheck
• fortress-security-scans.yml — security vulnerability scanning
• fortress-coverage.yml — coverage reporting to Codecov
• fortress-release.yml — automated binary releases via GoReleaser

See all workflows in .github/workflows/.

Updating Dependencies

To update all dependencies (Go modules, linters, and related tools) in a single step:

magex deps:update

Core dependencies (go-flywheel, go-foundation) are pinned; this keeps your development environment and CI in sync with the vetted versions.

🧪 Examples & Tests

All unit tests run via GitHub Actions. View the configuration file.

Run the tests (race + coverage):

magex test

Race detector only, or a coverage report:

magex test:race
magex test:coverage

Tests are co-located _test.go — no testdata/, no golden files. A Ledger is isolated with t.TempDir() + LUCID_HOME, the model is stubbed with provider.Fake, and the scheduler is driven by an injected now. Coverage reports are uploaded to Codecov on every commit.

🛠️ Code Standards

Read more about this Go project's code standards. Product orientation for Lucid lives in CLAUDE.md; engineering conventions live in .github/tech-conventions/.

🤖 AI Usage & Assistant Guidelines

Read the AI Usage & Assistant Guidelines for how AI is used in this project and how to interact with AI assistants. In Lucid itself, the runtime never depends on AI (P9): the daily surface completes with no model in the loop, and the AI is always a stateless analyst over an excerpt — never the system of record.

👥 Maintainers

MrZ

🤝 Contributing

View the contributing guidelines and please follow the code of conduct.

How can I help?

All kinds of contributions are welcome 🙌! The most basic way to show your support is to star 🌟 the project, or to raise issues 💬. You can also support this project by becoming a sponsor on GitHub 👏 or by making a bitcoin donation to ensure this journey continues indefinitely! 🚀

📝 License

This project is licensed under the terms of the LICENSE file at the repo root.

We were all born without the manual. This is how you write yours.