Metadata-Version: 2.4
Name: solly
Version: 0.3.0
Summary: Solly: a persistent, provider-agnostic AI orchestration layer for software engineering workflows.
Author: CreativesCastle
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://github.com/creativescastle/solly
Project-URL: Repository, https://github.com/creativescastle/solly
Project-URL: Issues, https://github.com/creativescastle/solly/issues
Keywords: ai,orchestration,developer-tools,cli,engineering-workflow
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: PyYAML>=6.0
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn>=0.29
Requires-Dist: jinja2>=3.1
Requires-Dist: python-multipart>=0.0.9

# Solly

Solly is a persistent, provider-agnostic AI orchestration layer for
software engineering — plan, build, and review workflows that run
deterministically wherever possible and call an LLM only for genuine
judgment. It is one reusable engine shared across every project you
connect it to; each project owns only its own lightweight `.solly/`
workspace (plans, decisions, reviews, state) — no Solly source code is
ever copied into a project.

```bash
curl -fsSL https://install.solly.dev | bash
```

Then, in any project:

```bash
cd my-project
solly init
solly status
```

And later, when a new Solly release exists:

```bash
solly update
```

(Contributing to Solly itself instead of just using it? See "Contributor
Installation" below — a different install path from the one above.)

---

## What Solly is

- **One engine, many projects.** Solly is not tied to any single company
  or product. It resolves which project you're in, loads only that
  project's own context, and never mixes state across projects.
- **Deterministic first, LLM second.** Routing, risk classification,
  verification, and workspace migration are plain Python — no model calls,
  no added context. LLM judgment is reserved for planning, implementation,
  and review, where it's actually needed. See `docs/architecture.md`.
- **Files, not chat history.** Plans, build results, reviews, and
  telemetry are persisted as files under a project's `.solly/` workspace
  (or, for engine-global state, under `~/.solly`) — durable across
  sessions and Solly upgrades, not dependent on conversation memory.
- **Today's capability:** AI-assisted software engineering via three
  Claude Code skills — `solly-plan`, `solly-build`, `solly-review` (see
  `integrations/claude-code/skills/`; these three currently require a
  git checkout — see `docs/publishing.md` for exactly why, and why that's
  not fixable by Python packaging). The `solly` CLI itself has no such
  requirement — a `pip`/`uv tool` install has complete, verified runtime
  behavior on its own (same doc). The CLI in this README is the
  installation, lifecycle, and workspace-migration foundation the skills
  (and a future interactive assistant) run on.

---

## User Installation

This is the path for using Solly on your own projects. If you're
contributing to Solly's own source instead, skip to "Contributor
Installation" below.

### Prerequisites

- macOS or Linux (Windows: run inside WSL).
- Nothing else. The installer bootstraps everything it needs — including
  Python itself, via `uv` — from a bare machine.

### Install

```bash
curl -fsSL https://install.solly.dev | bash
```

This is a small bootstrap script (`install.sh` in this repository — read
it before piping it to `bash` if you'd like, that's always a reasonable
thing to do with any installer). All it does: check the platform, install
[`uv`](https://docs.astral.sh/uv/) if missing, install or upgrade Solly
via `uv tool`, and verify both `uv --version` and `solly --version`
actually run. It never touches `~/.solly`, any workspace-root `.solly/`,
or any project's `.solly/` — only the `solly` CLI installation itself.
Safe to re-run any time; re-running it is also how you update later (see
"Updating Solly" below for the single-command version, `solly update`).

**Fallback**, if `install.solly.dev` is unreachable or you'd rather run
the underlying command yourself (`uv` already installed):

```bash
uv tool install solly
```

(GitHub/raw-content hosts occasionally return `HTTP 429` under rate
limiting — if `curl` reports that, wait a few seconds and retry, or use
the fallback command above, which talks to PyPI instead.)

Verify the install:

```bash
solly --version
```

### First-time setup, start to finish

```bash
mkdir -p ~/AIWorkspace && cd ~/AIWorkspace
solly workspace init
```

```
Workspace root: ~/AIWorkspace
✓ Created .solly/workspace.yaml (name: AIWorkspace)
✓ Registered as "aiworkspace" in the Solly workspace-root registry
```

This is optional and purely organizational (see "Register a workspace
root" below) — Solly does not require it, does not require exactly one
per machine, and does not require your projects to live under it. You
can register any number of workspace roots at arbitrary absolute paths
(`~/Work`, `~/Personal`, `/Volumes/Clients`, ...); `solly workspace list`
shows every one registered on this machine.

```bash
cd Projects/MyProject   # or wherever your project lives
solly init
```

Registers the project and creates its `.solly/` workspace. Optionally
associate it with a company (groups it under a shared, cross-project
company brain — see "Companies and the Brain" below):

```bash
solly init --company acme
```

```bash
solly status
```

```
Solly 0.3.0
Project: myproject (acme)
Root: ~/AIWorkspace/Projects/MyProject
Workspace: ~/AIWorkspace/Projects/MyProject/.solly
Workspace root: AIWorkspace (~/AIWorkspace)
Workspace schema version: 2 (current)
Migration required: no
Workspace health: ok
Capabilities: engineering
```

```bash
solly doctor    # read-only diagnostics; add --fix to apply the same safe migration `solly init` runs
```

Optionally, start the dashboard:

```bash
solly dashboard --company acme
```

opens the Today/Ask Solly/Projects/Decisions/Knowledge dashboard at
`http://127.0.0.1:8765`.

A workspace root registered this way looks like:

```text
~/AIWorkspace/
├── .solly/
├── Solly/
└── Projects/
```

— but this is a convention, not a requirement. Nothing above enforces
this shape; projects scattered across unrelated directories, or a
workspace root with a different name entirely, work identically.

---

## Register a workspace root (optional)

If your projects live together under one parent directory (e.g.
`~/AIWorkspace`, containing `Solly/`, `Legible/`, `KinderOS/`, ...),
register that parent as a workspace root once:

```bash
cd ~/AIWorkspace
solly workspace init
```

This creates `~/AIWorkspace/.solly/workspace.yaml` — identity metadata
only (schema version, name, type). It holds no project or company state;
each project inside still gets its own `.solly/` via `solly init` (below),
run individually per project. Registering a workspace root is entirely
optional and purely informational (`solly status`/`solly workspace
status` will report which root, if any, contains the current project) —
nothing else changes behavior. You can register any number of workspace
roots at arbitrary absolute paths (`solly workspace list` shows them
all); Solly never assumes there's exactly one, or that your projects live
under any particular directory.

```bash
solly workspace list      # every registered workspace root
solly workspace status    # the root containing the current directory, if any
```

## Initialize Solly inside a project

From the project's root directory:

```bash
cd my-project
solly init
```

This creates (or, if `.solly/` already exists, safely updates) the
project's workspace: `.solly/project.yaml` (created with defaults derived
from the directory name if absent, otherwise left untouched beyond adding
any genuinely missing fields), a `workspace.json` schema-version marker,
and the canonical directories described below. It registers the project
by name so it can be resolved from anywhere afterward. **`solly init` is
always safe to re-run** — every step it takes is additive or merge-only;
it never overwrites or deletes anything a project already has.

If `.solly/` predates workspace versioning (no `workspace.json`), `solly
init` detects that and migrates it in place through the same versioned
migration framework `solly update` uses — see "Updating Solly does not
replace your project's knowledge," below.

## Start Solly

```bash
solly
```

Locates the nearest `.solly/` workspace (walking up from your current
directory), validates it, and confirms Solly is ready for that project.
This milestone's `solly` does not yet run a full interactive assistant —
today, use the `/solly-plan`, `/solly-build`, and `/solly-review` Claude
Code skills, which already operate on the same `.solly/` workspace `solly`
resolves. `solly` resolving readiness here is deliberate: the interactive
assistant becomes this same command's default behavior in a future
milestone, without changing how you invoke it.

## Companies and the Brain

Above projects sits a company layer: `solly company init <slug>` creates
a company workspace under `~/.solly/companies/<slug>/`, with its own
isolated knowledge store (one SQLite file per company — cross-company
leakage is structurally impossible, not just avoided by convention). A
project links to its company via `solly init --company <slug>`, which
additively creates the company workspace too if it doesn't exist yet.

```bash
solly company init procore --name Procore
solly company list                  # every company registered on this machine
cd my-related-items-project && solly init --company procore

solly brain add --company procore --type decision \
  --title "External items get a badge" --text "..."

solly dashboard --company procore   # opens the Today/Ask Solly/Projects/
                                     # Decisions/Knowledge dashboard at
                                     # http://127.0.0.1:8765
```

`solly brain add` (and the dashboard's "+ Add to Brain") is manual-only
for now — Solly never invents company, personal, or project knowledge on
its own; you teach it explicitly. Ask Solly currently does real evidence
retrieval against what you've added (with an honest "I don't have enough
information" when nothing matches) — LLM-based synthesis on top of that
evidence is a deliberate fast-follow, not yet wired up.

A project's slug (its identity in the registry, `project.yaml`, and any
brain rows scoped to it) is independent of its directory name — set once
at first `solly init`, from the directory name at that time. To correct
it later without touching the directory on disk:

```bash
solly project rename relateditems related-items
```

Updates the registry key, `project.yaml`'s `name` field, and migrates any
brain rows already scoped to the old slug — all in one operation, so the
registry and `project.yaml` never fall out of sync.

To remove a stale registry entry (e.g. a project whose directory no
longer exists) without touching anything on disk:

```bash
solly project unregister some-old-slug
```

Refuses by default if the slug still resolves to a live project on disk
(`.solly/project.yaml` present) — pass `--force` to unregister one
anyway. Either way, this only ever removes the registry entry; the
project's own files, `.solly/` workspace, and company brain data are
never touched.

## Updating Solly

```bash
solly update
```

is the single supported way to update — run it inside any registered
project. It does two things, in order, every time:

1. **Upgrades the installed engine.** For a normal (non-editable)
   install, this runs `uv tool upgrade solly` and then actually executes
   the newly-installed `solly --version` to confirm the upgrade didn't
   just replace files but produced something that still runs — a
   distinct, explicit "verified" step, not assumed from `uv`'s own exit
   code alone. **For an editable/development install, this step is
   skipped** with a clear message — see "Contributor Installation" below
   for how a development install updates instead.
2. **Migrates the current project's workspace**, if its schema is behind
   the engine's current version — the exact same safe, additive migration
   `solly init` runs. This step always runs, for both install modes,
   immediately after step 1 — so `solly update` is also the right command
   to run just to bring a project's `.solly/` workspace current,
   independent of whether the engine itself needed upgrading.

```
Solly 0.4.0
Project: Procore
✓ Engine updated 0.3.2 → 0.4.0
✓ Verified: installed `solly` executes successfully
✓ Workspace migrated 3 → 4
✓ Existing knowledge preserved
✓ Existing decisions preserved
✓ Validation passed

Procore is ready.
```

**The distribution pipeline this is built on**, end to end:

```text
Developer  →  GitHub  →  GitHub Release (tag)  →  PyPI  →  user's `uv tool upgrade solly`
```

A tagged, published GitHub Release triggers an automated, token-free
publish to PyPI (`.github/workflows/publish.yml`, PyPI Trusted
Publishing — see `docs/publishing.md` for the full pipeline and the
one-time PyPI-side setup it depends on). Once a release has gone through
that pipeline, `uv tool upgrade solly` — and therefore `solly update` and
the bootstrap installer above — pulls it from PyPI, the same as any other
published Python package. Until the first release has gone through this
pipeline, the fallback GitHub install
(`uv tool install git+https://github.com/creativescastle/solly.git`)
remains the working path.

## Uninstalling Solly

```bash
uv tool uninstall solly
```

Removes the `solly` CLI itself — nothing else. This deliberately does
**not** touch:

- `~/.solly` — the engine-global home (project/workspace-root registries,
  company brains, telemetry)
- any workspace root's `.solly/workspace.yaml`
- any project's `.solly/` workspace (plans, decisions, reviews, knowledge)

All of that is independent of whether the `solly` CLI happens to be
installed — reinstalling later (`curl -fsSL https://install.solly.dev |
bash`) picks every registered project and company right back up exactly
where it left off, with nothing to restore.

If you genuinely want to remove that data too (rare — this is real,
non-recoverable project/company history):

```bash
rm -rf ~/.solly                        # every company brain, every registry entry
rm -rf /path/to/some-workspace-root/.solly   # one workspace root's identity marker
rm -rf /path/to/some-project/.solly          # one project's plans/decisions/knowledge
```

None of these are run by `uv tool uninstall` or by any Solly command —
they're listed here only so an intentional full removal doesn't require
guessing at paths.

## Troubleshooting

- **`solly: command not found` right after installing.** A piped
  `curl | bash` runs in a subprocess and can't modify your *current*
  terminal's `PATH` — only new terminals pick up shell-profile changes
  automatically. The installer prints an explicit `source
  $HOME/.local/bin/env` line at the end when this applies to your
  session; run that once, or just open a new terminal tab.
- **`uv: command not found` after the installer claims success.** Same
  cause as above — `uv` installs to `$HOME/.local/bin` too. Same fix.
- **`curl` returns `HTTP 429`.** GitHub/raw-content hosts rate-limit
  anonymous requests occasionally. Wait a few seconds and retry, or use
  the fallback command: `uv tool install solly`.
- **`solly update`'s engine-upgrade step reports "not verified."** The
  files were replaced but the new `solly --version` didn't run cleanly —
  run `solly --version` yourself to see the actual error (usually a
  missing new dependency after an interrupted upgrade). Re-running `uv
  tool install --reinstall solly` resolves most cases.
- **Something looks wrong with a project's workspace.** `solly doctor`
  is always the first thing to run — read-only diagnostics that never
  modify anything unless you pass `--fix`.
- **None of the above.** `solly status` and `solly doctor`'s output is
  safe to share when asking for help — neither ever prints secrets or
  full config contents, per their own design (see "Check health" below).

## Check health

```bash
solly status    # concise project/workspace summary — never dumps secrets or config contents
solly doctor     # read-only diagnostics: broken/outdated state, missing files, registry drift
solly doctor --fix   # applies the same safe, additive migration `solly init` does — nothing else
```

`solly doctor` never deletes or silently rewrites your data; `--fix` is
the one explicit, opt-in exception, and it only ever runs the same
additive migration described below.

## What `.solly/` contains

```
.solly/
  project.yaml      identity, capabilities, verification commands (project-owned)
  workspace.json     schema version + migration history (Solly-managed)
  current-state.md    short "where things stand" snapshot
  architecture.md      project-specific constraints Solly should respect
  plans/                 one file per plan (solly-plan)
  tasks/                   one file per build task/result (solly-build)
  reviews/                  one file per review (solly-review)
  decisions/                 decision records — both solly-plan/review's and
                               solly brain add --type decision's write-ups
  knowledge/                  raw files ingested via `solly brain add`
  context/                     reserved
  assistant/                    reserved
  sessions/                      reserved
```

No Solly engine source code lives here — ever. Telemetry
(`docs/telemetry.md`), the project registry, and a project's *company*
(`~/.solly/companies/<slug>/` — see "Companies and the Brain" above) are
all engine-global, under `~/.solly` (overridable via `SOLLY_HOME`), not
per-project — so a project's `.solly/` stays small, portable, and safe to
commit to that project's own repository.

## Updating Solly does not replace your project's knowledge

This is the single most important guarantee of the update/migration
system: **`solly update` and `solly init` never reset, overwrite, or
delete anything already in a project's `.solly/` workspace.** Every
workspace migration (`src/solly/workspace/migrations/`) is additive by
design — it only creates files/directories that don't exist yet, records
what it did in `workspace.json`'s migration history, and is safe to
interrupt or re-run at any point. Your plans, build results, reviews,
decisions, and any files you've added yourself survive indefinitely across
Solly upgrades. If a future migration ever needs to transform (not just
add) an existing file, it's required to write a recovery copy first and to
fail loudly rather than risk data it can't guarantee it preserved.

---

## Contributor Installation

This is the path for working on Solly's own source — not for using Solly
on your other projects (see "User Installation" above for that).

```bash
git clone https://github.com/creativescastle/solly.git Solly
cd Solly
uv tool install --editable .
```

This installs the same `solly` console script, but backed by your local
checkout — edits to the checkout take effect immediately, without
reinstalling. **An editable install never pulls from PyPI or GitHub** —
it only ever reflects whatever is currently on disk in that checkout.
`git pull` in the checkout is how a development install "updates"; see
"Updating Solly" above for exactly how `solly update` treats an editable
install differently (it skips the engine-upgrade step with a clear
message, rather than pretending to upgrade something that has no
"latest release" to move to). If the pulled commits changed
`pyproject.toml`'s dependencies or added a new top-level package, `git
pull` alone won't reflect that — rerun `uv tool install --reinstall
--editable .` as well.

The install mechanism is intentionally isolated behind one small module
(`src/solly/cli/engine_upgrade.py`) precisely so the installation source
— GitHub, PyPI, editable for contributors — never requires touching
workspace/migration logic.

### Running the test suite

```bash
git clone https://github.com/creativescastle/solly.git Solly
cd Solly
uv venv .venv
uv pip install --python .venv/bin/python -e .
.venv/bin/python -m unittest discover -s tests -t .
```

The package must be installed (editable is fine) before running the test
suite — `tests/` imports `solly.*` as a real installed package, not via a
`sys.path` trick. `tests/__init__.py` isolates `SOLLY_HOME` and
`SOLLY_TELEMETRY_PATH` to throwaway temp directories for the whole test
session, so running tests never touches a real installation's `~/.solly`.

`uv run pytest` is the equivalent one-liner if you're using `uv` for the
whole workflow (`uv sync` first to pick up the `dev` dependency group).

See `CLAUDE.md` for the full architecture and operating rules, and
`docs/architecture.md` / `docs/project-integration.md` /
`docs/publishing.md` / `docs/telemetry.md` for the deeper documentation
this README intentionally stays short and points to rather than
duplicating.

## Versioning

Several independent version numbers, each tracking a different thing and
bumped separately — an application release doesn't imply any of the
others changed:

- **Solly application version** (`solly --version`, `pyproject.toml`'s
  `[project].version`) — bumps on engine/CLI releases.
- **Project workspace schema version** (`solly status`, `.solly/workspace.json`) —
  bumps only when a project's `.solly/` structure changes
  (`src/solly/workspace/schema.py`).
- **Company workspace schema version** (`~/.solly/companies/<slug>/company.yaml`) —
  bumps only when the company workspace structure changes
  (`src/solly/company/schema.py`).
- **Brain schema version** (`brain.db`'s internal `brain_meta` table) —
  bumps only when the Source/Decision/ContextEntry table shapes change
  (`src/solly/brain/schema.py`).

Releases are tagged semantic versions (`vX.Y.Z`) against this repository's
GitHub remote and published to PyPI from that tag (see "Updating Solly"
above, `docs/publishing.md`); `solly --version` is always the
authoritative, programmatically-checkable answer for which engine version
is installed.
