Make Longevity OS portable, grounded, and ClawHub-deployable

[llj0824]

Visual explainer

Start here for the fast architectural read: PR 4 Deep Dive | Longevity OS Portability

This HTML artifact walks through the runtime shape after the PR, the gap it closes, the concrete code surfaces involved, and the verification stack behind the portability claim.

---

What this PR does

This PR makes Longevity OS runnable anywhere — not just on your local machine. It also replaces every agent's raw-SQL-via-imaginary-CLI pattern with real, tested Python scripts that read and write the SQLite database.

Before these changes, every path in the codebase was hardcoded to /Users/A.Y/Desktop/Projects/2026/longevity-os/.... The agents told the AI to run commands against that path, which obviously doesn't work for anyone else — or for ClawHub deployment.

After these changes, the system resolves paths at runtime, every write goes through a dedicated script, and the whole bundle passes a portability validator.

---

High-level summary

1. Portable path resolution (paths.py)

A new top-level paths.py module replaces every hardcoded /Users/A.Y/... path in the codebase.

• get_project_root() — returns the mutable data directory. Defaults to a sibling folder longevity-os-data/ next to the repo, or reads from LONGEVITY_OS_PROJECT_DIR env var.
• get_db_path() — returns the SQLite path. Overridable via LONGEVITY_OS_DB_PATH.
• All existing modules (data/db.py, modeling/engine.py, modeling/causal.py, modeling/patterns.py, dashboard/server.py, every script) now import from paths.py instead of using string literals.

This means the same checkout works on your machine, Leo's machine, a ClawHub sandbox, or CI — no edits needed.

2. Grounded runtime scripts (11 new scripts)

Previously, agent prompts told the AI to run raw SQL via sqlite3 shell or a db.py CLI that didn't exist as described. Now each agent action maps to a real, tested script:

Script	What it does
scripts/log_meal.py	Accepts JSON on stdin, writes diet_entries + diet_ingredients, returns totals
scripts/log_metrics.py	Batch-writes body_metrics rows from JSON
scripts/log_exercise.py	Writes exercise_entries + exercise_details from JSON
scripts/log_biomarkers.py	Writes biomarkers rows from JSON
scripts/manage_supplements.py	Add/update/stop/list supplements with JSON payloads
scripts/query_sqlite.py	Safe read-only SQL query helper (returns JSON)
scripts/weekly_report.py	Generates a full weekly health report with trends, trial progress, and recommendations
scripts/trial_status.py	Returns structured trial status with phase detection and compliance tracking
scripts/demo_reset.py	Deterministic reset + seed + verify workflow for demos
scripts/install_openclaw_skill.py	Copies the skill bundle into an OpenClaw workspace
scripts/check_clawhub_bundle.py	Validates the repo is a portable, publishable ClawHub bundle

Every script:

• Auto-creates the DB and schema if missing (via scripts/setup.py)
• Resolves paths through paths.py
• Returns structured JSON so the AI agent can parse the result
• Works in isolated temp directories (important for tests and ClawHub)

3. Agent prompts updated

All 10 agent markdown files (agents/*.md) and the orchestrator (SKILL.md) were updated:

• Hardcoded /Users/A.Y/... paths replaced with {baseDir}/scripts/...
• Each agent now points to the specific script it should call (e.g., shiyi.md points to log_meal.py, daoyin.md to log_exercise.py)
• Added a rule: "do not claim success unless the script returns success"
• SQL examples updated to use SUBSTR(timestamp, 1, 10) instead of DATE(timestamp) for SQLite compatibility with ISO 8601 strings

4. SKILL.md routing and metadata

• Renamed skill from longevity-os to longevity (ClawHub convention)
• Added metadata.openclaw block with homepage and binary requirements
• Added explicit routing guidance (positive/negative trigger examples)
• Added orchestrator handoff phrasing guidance
• System paths now use {baseDir} placeholder that OpenClaw resolves at install time

5. SQLite DATE() fix across modeling layer

DATE(timestamp) doesn't work reliably on ISO 8601 strings with timezone offsets in SQLite. All queries in modeling/engine.py, modeling/causal.py, and modeling/patterns.py now use SUBSTR(timestamp, 1, 10) instead — a pattern that works correctly regardless of how the timestamp was stored.

6. Architecture docs in README

Added a comprehensive Architecture section to README.md with 6 Mermaid diagrams: system overview, data flow, ERD, agent dispatch sequence, trial state machine, and architectural boundaries. Plus subsystem breakdowns, dashboard API reference, and schema documentation.

7. Test coverage

4 new test files covering the critical paths:

• test_write_paths.py — meal logging, metric batch writes (isolated temp DB)
• test_read_paths.py — weekly report generation, trial status reads (seeded temp DB)
• test_runtime_surfaces.py — exercise logging, biomarker writes, supplement lifecycle
• test_openclaw_install.py — skill install, bundle validation, stale file detection, end-to-end runtime

All tests run against isolated temporary directories — no shared state, no hardcoded paths.

---

Data flow (before vs after)

Before:

User input → Agent prompt → AI generates raw SQL → sqlite3 /Users/A.Y/.../taiyiyuan.db

After:

User input → Agent prompt → AI calls python3 {baseDir}/scripts/log_meal.py → script resolves DB path → writes rows → returns JSON

---

Files changed: 46 files, +4,200 / -147

Category	Files
Path resolution	paths.py (new)
Write scripts	log_meal.py, log_metrics.py, log_exercise.py, log_biomarkers.py, manage_supplements.py (all new)
Read scripts	query_sqlite.py, weekly_report.py, trial_status.py (all new)
Infra scripts	demo_reset.py, install_openclaw_skill.py, check_clawhub_bundle.py (all new)
Existing scripts	setup.py, backup.py, export.py, migrate.py, import_apple_health.py, import_labs.py, generate_demo_data.py (path fixes)
Data layer	data/db.py, modeling/engine.py, modeling/causal.py, modeling/patterns.py (path + DATE fix)
Dashboard	dashboard/server.py (path fix)
Agent prompts	All 10 agents in agents/ + SKILL.md (grounded tool refs)
Tests	4 new test files in tests/
Docs	README.md architecture section, docs/ artifacts, screenshots/
Config	.gitignore, requirements.txt

---

How to verify

# Run the bundle portability check
python3 scripts/check_clawhub_bundle.py

# Run the full test suite (uses temp dirs, no side effects)
python3 -m pytest tests/ -v

# Reset and seed a demo database
LONGEVITY_OS_PROJECT_DIR=/tmp/longevity-demo python3 scripts/demo_reset.py

---

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 4.6 (1M context) noreply@anthropic.com