Environment #
Journal Path #
get_journal() / get_journal_info() in solstone.think.utils are the canonical journal resolvers. Trust them unconditionally.
Resolver order (with the source label get_journal_info() returns):
SOLSTONE_JOURNALenv var, when set and non-empty →"env"~/.config/solstone/config.toml, when it has a non-emptyjournal = "..."key →"config"- source-tree fallback:
<project_root>/journalwhen both<project_root>/pyproject.tomland<project_root>/.gitexist →"source" - built-in default:
~/journal→"default"
get_journal_info() no longer raises — there is always a resolved path. get_journal() raises SolstoneNotConfigured only when os.makedirs on the resolved path fails.
Who sets SOLSTONE_JOURNAL:
- Installed runs: the managed wrapper at
~/.local/bin/sol - Unit tests: the
set_test_journal_pathautouse fixture intests/conftest.py - Makefile sandboxes: explicit per-command env injection in
make sandbox/ verify targets
Who must not set it:
- application code
- service files
- agent prompts
- ad hoc subprocess environments spawned by app code
If you think you need to set SOLSTONE_JOURNAL from application code, fix the actual resolution problem instead.
Service Installation #
There are two install paths and they handle journal resolution differently. For a fresh source checkout, .venv/bin/journal setup installs managed bash wrappers at ~/.local/bin/sol and ~/.local/bin/journal, then installs solstone as a systemd user service (Linux) or launchd agent (macOS) with convey on port 5015. For packaged host installs (pip install solstone-journal, uv tool install solstone-journal && uv tool install solstone, or pipx install solstone-journal && pipx install solstone), journal setup also provisions those managed wrappers in-process, pointing them at the packaged runtime binaries. After setup, the wrappers let you use sol and journal from anywhere; override with .venv/bin/journal setup --port 8000 on the first source-checkout run or journal setup --port 8000 after the wrapper exists. If an existing alias is owned by another install, setup copies it to /tmp/<binary>.old-symlink-<timestamp> before atomically replacing both wrappers. Wrapper provisioning failures are non-fatal warnings so a later journal setup can retry. Both paths install the service.
Installed services invoke ~/.local/bin/journal. They do not write SOLSTONE_JOURNAL into the service env block; the wrapper exports it before execing the venv journal.
Use:
journal config showto display the resolved journal path, user-facing source label, and wrapper statusjournal config journal <path>to atomically rewrite the wrapper's embedded journal pathjournal service <install|start|stop|restart|status|logs>for service lifecycle management
API Keys #
Store API keys in .env file, never commit to repository.
Error Handling & Logging #
- Raise specific exceptions with clear messages
- Use logging module, not print statements
- Validate all external inputs (paths, owner data)
- Fail fast with clear errors - avoid silent failures
Documentation #
- Update README files for new functionality
- Code comments explain "why" not "what"
- Function signatures should include type hints; highlight gaps when touching older modules
- All docs in
docs/plus journal references insolstone/talent/journal/: Browsesolstone/talent/journal/SKILL.md, APPS.md, CORTEX.md, CALLOSUM.md, THINK.md, and more - Each package has a README.md symlink pointing to its documentation in
docs/. - App/UI work: docs/APPS.md is required reading before modifying
solstone/apps/
Git Practices #
- Git: Small focused commits, descriptive branch names. Run git commands directly (not
git -C) since you're already in the repo.
Getting Help #
- Run
solfor status and CLI command list - Check docs/DOCTOR.md for debugging and diagnostics
- Browse
docs/for all subsystem documentation - Review test files in
tests/for usage examples