segovia 0.1.0__tar.gz

segovia-0.1.0/.claude/hooks/publishing_reminder.py

@@ -0,0 +1,45 @@
+import json
+import sys
+import time
+from pathlib import Path
+
+CADENCE_DAYS = 7
+PROJECT = "Segovia"
+STATE_PATH = Path(__file__).resolve().parents[1] / "state" / "publishing_reminder.json"
+
+
+def load_last_epoch():
+    try:
+        return int(json.loads(STATE_PATH.read_text(encoding="utf-8")).get("last_epoch", 0))
+    except Exception:
+        return 0
+
+
+def save_epoch(epoch):
+    STATE_PATH.parent.mkdir(parents=True, exist_ok=True)
+    STATE_PATH.write_text(json.dumps({"last_epoch": epoch}), encoding="utf-8")
+
+
+def reminder_text():
+    return (
+        f"[{PROJECT}] Publishing reminder (every {CADENCE_DAYS} days): consider a milestone-only "
+        f"post for {PROJECT} and MaskOps - benchmark results, a release, or a tutorial, not every "
+        f"commit. LinkedIn: adapt assets/draft_linkedin_es.* (ES), best Tue/Wed 9-11h local, 3-5 "
+        f"hashtags. dev.to: a technical write-up mirroring the MaskOps cadence. Keep the honest "
+        f"ephys->leukemia arc (aided-by, not made-for)."
+    )
+
+
+def main():
+    now = int(time.time())
+    last = load_last_epoch()
+    if last and (now - last) < CADENCE_DAYS * 86400:
+        print(json.dumps({"suppressOutput": True}))
+        return 0
+    save_epoch(now)
+    print(json.dumps({"systemMessage": reminder_text(), "suppressOutput": True}))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

segovia-0.1.0/.claude/settings.json

@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python \"$CLAUDE_PROJECT_DIR/.claude/hooks/publishing_reminder.py\""
+          }
+        ]
+      }
+    ]
+  }
+}

segovia-0.1.0/.claude/skills/README.md

@@ -0,0 +1,12 @@
+# Project skills
+
+Project-scoped Claude Code skills live here, one directory per skill, each with a `SKILL.md`.
+They are invoked with `/<skill-name>` and are available to anyone working in this repository.
+
+Nothing is defined yet. Likely future candidates for Segovia:
+
+- a benchmark-runner skill (set up the SC1 gate run and collect memory/throughput numbers),
+- a release skill (changelog + version bump + tag, gated on explicit approval),
+- a dataset-fetch skill (pull free IBL/DANDI/SpikeGLX fixtures for tests).
+
+Hooks (automated, non-invokable behaviors) live in `../hooks/` and are wired in `../settings.json`.

segovia-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,23 @@
+---
+name: Bug report
+about: Report a problem with Segovia
+title: ""
+labels: bug
+---
+
+**Describe the bug**
+A clear description of what is wrong.
+
+**To reproduce**
+Minimal steps or code to reproduce.
+
+**Expected behavior**
+What you expected to happen.
+
+**Environment**
+- OS:
+- Python version:
+- Segovia version / commit:
+
+**Additional context**
+Anything else relevant — data shape, recording size, stack trace.

segovia-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Discussions
+    url: https://github.com/fcarvajalbrown/Segovia/discussions
+    about: Questions, ideas, and design discussion.

segovia-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,18 @@
+---
+name: Feature request
+about: Suggest an idea or improvement for Segovia
+title: ""
+labels: enhancement
+---
+
+**Problem / motivation**
+What problem would this solve?
+
+**Proposed solution**
+What you would like to happen.
+
+**Alternatives considered**
+Other approaches you have weighed.
+
+**Additional context**
+Anything else — links, datasets, prior art.

segovia-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,19 @@
+## Situation
+_What's the context and the problem this addresses?_
+
+## Task
+_What does this PR set out to do?_
+
+## Action
+_What changes were made?_
+
+## Result
+_What's the outcome — tests, benchmarks, behavior?_
+
+---
+
+- [ ] `cargo fmt --all -- --check` passes
+- [ ] `cargo clippy --all-targets -- -D warnings` passes
+- [ ] `cargo test` passes
+- [ ] Conventional commits; one commit per logical change
+- [ ] No code comments; `ROADMAP.md` / `CHANGELOG.md` updated for any user-visible change

segovia-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,55 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint-test:
+    name: fmt + clippy + test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo fmt --all -- --check
+      - run: cargo clippy --all-targets -- -D warnings
+      - run: cargo test --all
+
+  wheels:
+    name: build wheels (${{ matrix.os }})
+    needs: lint-test
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          command: build
+          args: --release --out dist
+          manylinux: auto
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.os }}
+          path: dist

segovia-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,96 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  verify-version:
+    name: verify tag matches Cargo.toml version
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Assert git tag equals crate version
+        run: |
+          crate_version=$(grep -m1 '^version' Cargo.toml | sed -E 's/.*"(.*)".*/\1/')
+          tag="${GITHUB_REF_NAME}"
+          echo "tag=$tag crate_version=$crate_version"
+          if [ "$tag" != "v$crate_version" ]; then
+            echo "::error::release tag '$tag' does not match Cargo.toml version 'v$crate_version'"
+            exit 1
+          fi
+
+  publish-crate:
+    name: publish crate (crates.io)
+    needs: verify-version
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo publish
+        env:
+          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+
+  build-wheels:
+    name: build wheels (${{ matrix.os }})
+    needs: verify-version
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          command: build
+          args: --release --out dist
+          manylinux: auto
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.os }}
+          path: dist
+
+  build-sdist:
+    name: build sdist
+    needs: verify-version
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build sdist
+        uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist
+
+  publish-pypi:
+    name: publish to PyPI
+    needs: [build-wheels, build-sdist]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/segovia/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - uses: pypa/gh-action-pypi-publish@release/v1

segovia-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+/target
+**/*.rs.bk
+
+.venv/
+venv/
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.pyd
+*.dylib
+
+dist/
+build/
+wheelhouse/
+*.egg-info/
+.eggs/
+
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+*.profraw
+
+.DS_Store
+Thumbs.db
+
+.claude/state/
+.claude/settings.local.json
+
+.env

segovia-0.1.0/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-09
+
+### Added
+- Initial repository scaffold: Rust crate + PyO3/maturin Python packaging, architecture docs,
+  AGPL-3.0-or-later license, CI, and contributor/community files.
+- Day-1 zero-copy bridge spike: `segovia.zeros(channels, samples)` returns an `int16` NumPy array
+  backed by Rust-owned memory (no copy), plus `segovia.__version__`.
+- Chunked, memory-bounded SpikeGLX reader (`segovia.SpikeGlxReader`): parses the `.meta` sidecar
+  (channel count, sample rate, stream type, declared file size, raw fields), memory-maps the `.bin`,
+  and streams it in fixed-size `(samples, channels)` `int16` chunks via `reader.chunks(chunk_samples)`
+  with the GIL released during each chunk copy. Sample count is derived from the **actual** `.bin`
+  size and validated for frame alignment; a stale or truncated meta `fileSizeBytes` is tolerated and
+  surfaced via the `declared_file_size_bytes` property. Validated byte-for-byte against the real
+  `Noise4Sam_g0` Neuropixels recording from the NEO `ephy_testing_data` corpus.
+
+[Unreleased]: https://github.com/fcarvajalbrown/Segovia/commits/main

segovia-0.1.0/CITATION.cff

@@ -0,0 +1,26 @@
+cff-version: 1.2.0
+message: "If you use Segovia in your research, please cite it as below."
+title: "Segovia: a chunked, memory-bounded Rust engine for electrophysiology signal processing"
+abstract: >-
+  Segovia is a lazy-evaluated, chunked, concurrent Rust compute engine for massive multi-channel
+  electrophysiology time-series (Neuropixels-scale), exposed to Python via PyO3 and built to
+  integrate with the SpikeInterface ecosystem over SpikeGLX, Zarr, and NWB. It targets bounded-memory,
+  out-of-core streaming preprocessing with GIL-released shared-memory threading.
+type: software
+authors:
+  - given-names: Felipe
+    family-names: "Carvajal Brown"
+    email: fcarvajalbrown@gmail.com
+keywords:
+  - neuroscience
+  - electrophysiology
+  - neuropixels
+  - spike-sorting
+  - signal-processing
+  - rust
+  - python
+  - out-of-core
+license: "AGPL-3.0-or-later"
+repository-code: "https://github.com/fcarvajalbrown/Segovia"
+version: 0.1.0
+date-released: 2026-06-09

segovia-0.1.0/CLAUDE.md

@@ -0,0 +1,193 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working in this repository.
+
+## How I want you to work with me
+
+**Decisions are mine — present them interactively.** When a choice is mine to make, ALWAYS
+present it as an interactive multiple-choice question I answer with the arrow keys (the
+`AskUserQuestion` picker), with a recommended option marked. Never bury a decision in prose
+and proceed. Never present a wall of options as plain text when the picker will do.
+
+**Always ask, never assume.** If any detail is unclear, unspecified, or ambiguous, stop and
+ask before writing code or documents. Do not guess. Do not fill gaps with assumptions and
+keep going. A wrong assumption costs more than a question.
+
+**Work sequentially and confirm direction.** Prefer one step at a time. Before any large or
+hard-to-reverse change, confirm the approach with me first. Show me the plan, get a yes, then act.
+
+**Report honestly.** If something failed, say so with the output. If a step was skipped, say
+that. State what a thing does and what it does not do. No hedging, no inflation.
+
+## Code style
+
+- **No comments of any kind.** No `//`, `///`, `//!`, `/* */` in Rust; no `#` comments or
+  docstrings in Python. Names and types are the only documentation.
+- **Bug fixes target root cause only** — never patch test parameters or add workarounds to
+  make tests pass. Never write code just to make it compile; code must reflect real behavior.
+
+## Rust conventions
+
+- `thiserror` for error types in libraries.
+- `serde` + `serde_json` for serialization.
+- `rayon` for parallelism.
+- Release the GIL (`Python::allow_threads`) around all heavy Rust work — see the architecture docs.
+
+## Python / build (Windows-first)
+
+- Always work inside a `.venv` at the project root. Never assume one exists — check or create it.
+- On Windows (PowerShell): run each command separately, **no `&&`** chaining.
+- `maturin develop --release` recompiles Rust + installs the editable Python package. **Re-run it
+  after any Rust change** before running Python or tests.
+- The Rust↔Python bridge is **`pyo3` 0.28**; the scaffold compiles clean (`cargo check`). No Polars
+  dependency, so the MaskOps `pyo3`/`pyo3-polars` coupling lesson does not apply — but still never
+  bump `pyo3` blindly.
+- Known CI realities to watch (precedent from my MaskOps project): Windows wheel building +
+  HDF5 C-library linking is painful; MaskOps had to exclude Ubuntu + Python 3.12 from the test
+  matrix over a `dlopen` failure. Expect platform-specific extension-load issues.
+
+## Commits
+
+- Conventional commits: `<type>(<scope>): <description>` — lowercase, present-tense imperative.
+  Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `ci`.
+- **One commit per logical change** — no layer-split commits.
+- **No AI attribution anywhere** — no `Co-Authored-By`, no "Generated with Claude Code" in
+  commit messages, PR descriptions, or code.
+- Never force-push without telling me and waiting for confirmation.
+
+## Branches, PRs, releases
+
+- **Branch only for roadmap work** (a feature/fix listed on the roadmap). Tooling, config, and
+  housekeeping go directly to `main`.
+- **PR descriptions in STAR format:** Situation / Task / Action / Result.
+- **Version sources of truth — keep them in lockstep.** `Cargo.toml` `version` is the *machine*
+  source of truth: `pyproject.toml` carries no static version (`dynamic = ["version"]`), so `maturin`
+  derives the wheel version from `Cargo.toml`, and the git tag `vX.Y.Z` must equal it (CI fails the
+  publish on mismatch). `ROADMAP.md` is the *human* source of truth for version + scope and must
+  state the same number. Read `ROADMAP.md` before any version or release action.
+- **Finishing a task includes updating `ROADMAP.md` and the changelog** — automatically, as the
+  last step of any user-visible change. Pure chore/docs/ci/tooling work touches neither.
+- **A release is a deliberate roadmap event, and every approved roadmap PR ships one.** My **"yes"
+  to the PR is the release approval** — no separate tagging or merge approval. **PRs and branches are
+  a formality to keep history clean**, so Claude drives them end to end: open the PR with a
+  conventional-commit title (its type drives the SemVer bump) → **wait for all GitHub Actions checks
+  to pass** → **Claude does the squash-merge** (don't wait for me to click merge) → after verifying
+  `main` actually contains the squash commit, cut the release (`cargo release <level> --execute`
+  bumps `Cargo.toml`, rewrites the doc surfaces, tags `vX.Y.Z`, pushes) → `gh release create`. The
+  published release triggers `release.yml`. **Never merge on red CI, and never tag code that is not on
+  `main`.** Pure chore/docs/ci/tooling work never releases.
+- **Announce releases via Discussions natively:** cut releases with
+  `gh release create <tag> --discussion-category "Announcements"` so GitHub auto-posts the release
+  notes as an Announcements discussion. No standing Action — it rides on the deliberate release step.
+
+### Versioning & release mechanics
+
+**One number; everything else derives from it — never hand-maintain a second copy.** `Cargo.toml`
+`version` is the only place a version is written. Every shipped surface reads from it, so they
+*cannot* drift:
+
+- **crates.io** ← `Cargo.toml` directly (it *is* the manifest).
+- **PyPI wheel + sdist** ← `maturin` reads `Cargo.toml`, because `pyproject.toml` declares
+  `dynamic = ["version"]` and carries **no** static `version` field. (This is the exact MaskOps
+  trap — a hand-kept `pyproject` version — and it is now structurally impossible.)
+- **`segovia.__version__`** ← `env!("CARGO_PKG_VERSION")` in `src/lib.rs`, i.e. `Cargo.toml` at
+  compile time.
+- **git tag** ← `cargo-release` creates `v{{version}}` from `Cargo.toml`; then `release.yml`'s
+  `verify-version` job re-asserts `tag == Cargo.toml version` and **fails the publish on any
+  mismatch** (belt and suspenders).
+
+The only files that hold a *literal* number are docs, and `cargo-release` rewrites them in the same
+bump commit via `pre-release-replacements` (`release.toml`): `CHANGELOG.md` (`[Unreleased]` → version
++ date), `CITATION.cff` (`version:` + `date-released:`), and `ROADMAP.md` (`**Version:**`). So **a
+release is one command** — `cargo release <minor|patch> --execute` — and nothing is edited by hand.
+
+- **SemVer, pre-1.0 (`0.MINOR.PATCH`):** `feat` → minor; `fix`/`perf`/`refactor` → patch; a breaking
+  change (`!` / `BREAKING CHANGE`) → minor while `< 1.0`. `chore`/`docs`/`ci`/`style`/`test` alone →
+  no release. The squash-merge's conventional-commit type selects the bump.
+- **Publish pipeline:** publishing a GitHub release (`gh release create v* --discussion-category
+  "Announcements"`) fires `release.yml` → `verify-version` → `cargo publish` (via the
+  `CARGO_REGISTRY_TOKEN` secret) + maturin wheels/sdist → PyPI via Trusted Publishing (OIDC, the
+  `pypi` environment; no token stored). `cargo-release` itself does **not** publish (`publish = false`).
+- **One-time setup state:** `release.yml`, `release.toml`, the `dynamic` pyproject switch, the
+  `CARGO_REGISTRY_TOKEN` secret, and the `pypi` environment are all in place. Still required on the
+  host that cuts a release: `cargo install cargo-release`; and PyPI's Trusted-Publishing entry for
+  this repo must exist before the first PyPI upload.
+
+## Automated publishing reminders (LinkedIn + dev.to) — ACTIVE
+
+A **Stop hook** is wired in `.claude/settings.json` running `.claude/hooks/publishing_reminder.py`.
+It surfaces a milestone-publishing reminder at most once every **7 days** (cooldown tracked in
+`.claude/state/publishing_reminder.json`, gitignored) via the hook's `systemMessage` output. The
+reminder covers **both Segovia and MaskOps** and nudges:
+
+- **LinkedIn** — adapt the Spanish draft/teaser in `assets/draft_linkedin_es.*`; best **Tue/Wed
+  9–11h** local; 3–5 hashtags; "saves" are the strongest signal.
+- **dev.to** — a technical write-up, mirroring the MaskOps dev.to cadence.
+
+Post **milestones only** (benchmark results, releases, tutorials) — never every commit — and keep the
+honest **ephys→leukemia arc** (aided-by, not made-for; never overclaim). To change the cadence, edit
+`CADENCE_DAYS` in the hook; to pause it, remove the `Stop` block from `.claude/settings.json`. Project
+skills (none yet) live under `.claude/skills/`.
+
+## Project state (2026-06-09)
+
+- **Repo:** https://github.com/fcarvajalbrown/Segovia (`origin`). **First runnable code landed** — the
+  day-1 zero-copy NumPy spike (`segovia.zeros`, `segovia.__version__`), merged via PR #2 with CI green
+  on Windows/macOS/Linux. The `segovia` crate is **published on crates.io at v0.0.0**
+  (AGPL-3.0-or-later, published manually 2026-06-09). **PyPI not yet.**
+- **Scaffold:** standalone `segovia` crate with `src/` core/ephys module seams, `pyproject.toml` +
+  maturin packaging, **AGPL-3.0-or-later** license, `.github/` CI (fmt/clippy/test + maturin wheel
+  matrix) and issue/PR templates, `ROADMAP.md` (version SSoT), `CHANGELOG.md`, `CITATION.cff`,
+  `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`, and a project `.venv`.
+- **Single-cell / leukemia vertical — deep-research COMPLETE.** Verdict: the out-of-core capability
+  gap is already closed (BPCells in C++, Scarf in Python), so the vertical survives only as a
+  *differentiation* play via **path E (interop)** built on **`scverse/anndata-rs`** — NOT a SingleRust
+  dependency (SingleRust is in-memory). Deferred and gated to a post-ship **M12+** phase. Full verdict
+  and the BPCells-Python monitor live in `docs/future/leukemia-direction.md`.
+- **GitHub page setup:** topics **set** ✅. Still TODO: set the About **description**, upload
+  `assets/segovia-social.png` as the social preview, set the Website field, enable Issues + Discussions.
+- **Next up (next session):** (1) **automate package publishing** — see the TODO below; (2) M0–2
+  roadmap work — the SpikeGLX `.meta`/`.bin` + Zarr chunked, memory-bounded reader.
+
+## TODO (next session) — automate package publishing ("set it and forget it")
+
+The crates.io publish was manual. Next session, wire publishing into CI so a deliberate release ships
+both packages automatically:
+
+- **Rotate keys.** Revoke the crates.io token used 2026-06-09 (it was pasted in chat) and create a
+  **new** crates.io token. For PyPI, prefer **Trusted Publishing (OIDC)** so no token is stored at all;
+  otherwise create a PyPI API token.
+- **Store them as GitHub Actions *secrets*** (encrypted) — **not** plaintext repo "variables": e.g.
+  `CARGO_REGISTRY_TOKEN` (and `PYPI_API_TOKEN` if not using Trusted Publishing).
+- **Add `.github/workflows/release.yml`** triggered on a `v*` tag / published GitHub Release: run
+  `cargo publish` for the crate and build + upload PyPI wheels via `PyO3/maturin-action`. Then a
+  release publishes both automatically — no manual `cargo publish`.
+- Keep a release deliberate (tag = approved event), and link each release to an Announcements
+  discussion (`gh release create <tag> --discussion-category "Announcements"`).
+
+## What this is
+
+**Segovia** — a lazy-evaluated, chunked, concurrent **Rust compute engine for massive
+multi-channel electrophysiology time-series** (Neuropixels-scale: 30 kHz × thousands of
+channels), exposed to Python via PyO3, integrating with the SpikeInterface ecosystem over
+SpikeGLX / Zarr / NWB. The name honors **Claudio Segovia**, a friend who died of leukemia at 26,
+and evokes the Aqueduct of Segovia — a continuous stream carried across a row of segmented stone
+arches, the metaphor for this engine's chunked, span-by-span streaming model.
+
+- **Target CPU, not GPU.** The workload is IO/memory-bound (~22 MB/s per probe). The value is
+  bounded-memory streaming preprocessing with GIL-released threading — not SIMD throughput.
+- **The differentiating win** over `SpikeInterface + Zarr/Dask` is true shared-memory threading
+  (Rayon, no pickle/process-pool overhead) and tighter memory bounds. This must be proven by
+  benchmark early (the M2–4 go/no-go gate) — see `docs/architecture/`.
+
+## Architecture docs
+
+Read these before substantive work:
+
+- `docs/architecture/ARD.md` — Architecture Requirements Document.
+- `docs/architecture/candidate-architectures.md` — candidate architectures, pros/cons, recommendation.
+- `docs/architecture/adr/` — Architecture Decision Records (one per significant decision).
+- `docs/architecture/tech-stack.md` — concrete crate choices and their sharp edges.
+- `docs/architecture/roadmap.md` — 12-month milestones and the benchmark go/no-go gate.
+- `docs/architecture/rust-neuro-research.md` — the fact-checked research dossier this project is founded on.
+- `docs/future/leukemia-direction.md` — the deferred, gated single-cell vertical and its deep-research verdict.

segovia-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,35 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a
+harassment-free experience for everyone, regardless of age, body size, visible or invisible
+disability, ethnicity, sex characteristics, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance, race, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and
+healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment include demonstrating empathy and
+kindness, being respectful of differing opinions and experiences, giving and gracefully accepting
+constructive feedback, and focusing on what is best for the community.
+
+Examples of unacceptable behavior include the use of sexualized language or imagery, trolling,
+insulting or derogatory comments, public or private harassment, publishing others' private
+information without permission, and other conduct which could reasonably be considered inappropriate
+in a professional setting.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project
+maintainer at **fcarvajalbrown@gmail.com**. All complaints will be reviewed and investigated promptly
+and fairly. The maintainer is obligated to respect the privacy and security of the reporter.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

segovia-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing to Segovia
+
+Thanks for your interest. Segovia is in an early, pre-implementation phase — the most useful
+contributions right now are issues, design feedback, and small focused PRs.
+
+## Development setup (Windows-first)
+
+A `.venv` at the project root is required. On Windows (PowerShell), run commands separately — do not
+chain with `&&`.
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+pip install maturin
+maturin develop --release
+```
+
+`maturin develop --release` recompiles the Rust extension and installs the editable Python package.
+**Re-run it after any Rust change** before running Python or tests.
+
+## Checks before opening a PR
+
+```powershell
+cargo fmt --all
+cargo clippy --all-targets -- -D warnings
+cargo test
+```
+
+## Conventions
+
+- **Conventional commits:** `<type>(<scope>): <description>` — lowercase, present-tense imperative.
+  Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `ci`. One commit per logical change.
+- **No code comments.** Names and types are the documentation.
+- **Bug fixes target the root cause** — no workarounds that only make tests pass.
+- **PR descriptions use STAR format:** Situation / Task / Action / Result.
+
+## Licensing of contributions
+
+Unless you state otherwise, any contribution you submit is licensed under
+**AGPL-3.0-or-later**, the same terms as the project, without any additional conditions.