solpbc.org / solstone
personal memory agent
0
Fork 0

Configure Feed

Select the types of activity you want to include in your feed.

solstone / CONTRIBUTING.md
9.4 kB

Contributing to solstone#

Thank you for your interest in contributing to solstone. This guide covers developing on solstone from a source checkout. If you just want to run the software, see INSTALL.md.

Prerequisites#

solstone development uses a source checkout, a repo-local Python environment, and the uv package manager.

Required everywhere:

  • Python 3.11 or later
  • uv
  • Git
  • ripgrep (rg)
  • ffmpeg for audio processing
  • minisign 0.12 for transparency signing checks

Linux is the primary development platform. macOS is supported. Source-checkout installs on Apple Silicon need Xcode command line tools to build the CoreML parakeet helper; packaged host installs (uv tool install solstone-journal && uv tool install solstone) on macOS 14 or newer ship the helper as a pre-built binary.

Fedora/RHEL:

sudo dnf install python3 git ripgrep ffmpeg minisign pipewire gstreamer1-plugins-base gstreamer1-plugin-pipewire pulseaudio-utils
curl -LsSf https://astral.sh/uv/install.sh | sh

Ubuntu/Debian:

sudo apt install python3 git ripgrep ffmpeg minisign pipewire gstreamer1.0-tools gstreamer1.0-pipewire pulseaudio-utils
curl -LsSf https://astral.sh/uv/install.sh | sh

Arch:

sudo pacman -S python git ripgrep ffmpeg minisign pipewire gstreamer gst-plugin-pipewire libpulse
curl -LsSf https://astral.sh/uv/install.sh | sh

macOS:

xcode-select --install
brew install python git ripgrep ffmpeg minisign uv

Source-checkout install#

git clone https://github.com/solpbc/solstone-journal.git
cd solstone-journal
make install
.venv/bin/journal setup

make install creates .venv/, syncs dependencies from pyproject.toml and uv.lock, installs the package in editable mode, regenerates router skill references, and refreshes the sol + journal project skill symlinks into the journal.

.venv/bin/journal setup runs doctor diagnostics, confirms the journal path, installs local transcription models, installs the sol user skill for Claude Code / Codex / Gemini when those agents are configured, installs the sol + journal router skills into the journal, creates or refreshes the source-checkout wrappers at ~/.local/bin/sol and ~/.local/bin/journal, and starts the background service. The default web interface listens on http://localhost:5015. Use .venv/bin/journal setup --port 8000 to choose another port on the first run.

After the first setup run, the wrapper lets you use sol from anywhere:

journal service status
journal setup

The source-checkout journal lives at journal/ inside the repo unless you pass --journal or have already configured another path.

Configure API keys in journal/config/journal.json. This file is the only key configuration method for source-checkout development:

mkdir -p journal/config
cat > journal/config/journal.json << 'EOF'
{
  "env": {
    "GOOGLE_API_KEY": "your-key-here"
  }
}
EOF
chmod 600 journal/config/journal.json

Replace your-key-here with your Google AI API key. Optional provider keys can be added to the same env object:

{
  "env": {
    "GOOGLE_API_KEY": "your-gemini-key",
    "OPENAI_API_KEY": "your-openai-key",
    "ANTHROPIC_API_KEY": "your-anthropic-key"
  }
}

journal.json contains API keys and credentials. Keep it private and restricted (chmod 600).

Seeding a dev/test journal from public media#

If you want a journal seeded with public-domain audio and screen media instead of your own journal material — useful for contributors who shouldn't be exposed to a maintainer's personal journal, integration-test scenarios, or a clean dev environment — see docs/FIELD_JOURNAL.md. The setup_field_journal.sh script at the repo root populates journal/chronicle/ from a local clone of solpbc/field_journal. It is opt-in and deliberately not part of make install or journal setup.

Repo layout#

Start with AGENTS.md or CLAUDE.md for the developer-facing repo map, layer hygiene rules, make targets, and coding invariants. Most implementation work lives in solstone/think/, solstone/observe/, solstone/convey/, solstone/apps/, solstone/talent/, and tests/.

For app work, read docs/APPS.md before changing solstone/apps/. For provider work, read docs/PROVIDERS.md. For journal layout, use solstone/talent/journal/SKILL.md.

Running the test suite#

Use the Makefile targets. The high-signal commands are:

make test-only TEST=tests/test_utils.py::test_foo
make test-app APP=settings
make test
make ci

Use make test-only and make test-app as the development loop. make test runs all unit tests — tests/ plus every solstone/apps/*/tests/, in one parallel run — after a format check. make ci is the canonical full gate: install checks plus the full unit suite. Run it once on the settled final tree before submitting, merging, or releasing, not before every intermediate commit.

make test-only TEST="-k test_foo"              # one test by name/pattern

All tests are fast unit/component tests (no real browser, live network, or API keys). For user-visible web changes, use the API verification target and review the live UI in a sandbox when relevant:

make verify-api    # check API baselines against a sandbox
make sandbox       # start a sandbox to review the live UI (make sandbox-stop when done)

See AGENTS.md for the full Makefile command table and docs/testing.md for test isolation details.

Developing on AI features#

macOS Apple Silicon: CoreML-accelerated parakeet#

Packaged installs of solstone on Apple Silicon Macs running macOS 14 or newer ship the CoreML transcription helper as a pre-built, signed, and notarized binary. No build step is required for owners using a packaged install.

Source-checkout installs build the helper locally so you can iterate on the Swift source:

make parakeet-helper

The built binary lives at:

solstone/observe/transcribe/parakeet_helper/.build/release/parakeet-helper

If you change the helper source, rebuild it before testing the CoreML parakeet path. Note that the runtime resolver prefers solstone/observe/transcribe/parakeet_helper/_bin/parakeet-helper (the location populated by make wheel-macos for platform-wheel packaging) over the .build/release/ path; if you previously ran make wheel-macos, run make wheel-macos-clean to clear the _bin/ copy so your local rebuild takes effect.

Skills and talents#

Talent prompts live under solstone/talent/<name>.md; apps may add app-specific talent files under solstone/apps/<app>/talent/. Talent frontmatter declares type, schedule, provider/model behavior, hooks, priority, and output expectations.

The installed project skills are the two router skills under solstone/talent/sol/ and solstone/talent/journal/. App command fragments under solstone/apps/<app>/talent/<app>/SKILL.md feed the generated router references; they are not installed as top-level skills.

After changing a router skill or an app command fragment, run:

make skills

That target first runs scripts/build_skill_references.py to regenerate the checked-in references, then refreshes the sol + journal router skill symlinks inside the journal. make install also runs this target, and make ci / make install-checks runs scripts/build_skill_references.py --check to catch stale generated references.

Migrating from a source install to a packaged install#

A packaged host install puts sol, solstone, journal, and mlx-vlm-server on PATH directly. pip install solstone-journal exposes those commands in one environment; uv tool and pipx expose each tool's own commands, so install both the journal tool and the thin solstone tool. It does not use the source-checkout managed wrapper, and it does not use .venv/bin/sol.

make uninstall is disabled by design. To migrate cleanly from a source checkout to a packaged install, remove user-runtime artifacts explicitly:

journal service uninstall
sol skills uninstall
python -m solstone.think.install_guard uninstall
uv tool install solstone-journal && uv tool install solstone
journal setup

For pip or pipx packaged installs, use pip install solstone-journal or pipx install solstone-journal && pipx install solstone before journal setup.

Your journal is preserved at ~/journal; solstone does not remove it during install or uninstall. Do not add backwards-compatibility shims for the old source-checkout layout. This migration is a clean break.

License of Contributions#

By contributing to this repository, you agree that your contributions are licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-only), the same license as the project.

You represent that you have the right to submit the contribution and that it does not include proprietary, confidential, or third-party code that is incompatible with the AGPL.

Developer Certificate of Origin (DCO)#

All contributions must be signed off using:

git commit -s

This certifies compliance with the Developer Certificate of Origin (DCO).