axon-context-mcp 0.1.1__tar.gz

axon_context_mcp-0.1.1/.claude/loop.yaml

@@ -0,0 +1,43 @@
+# Onboards axon to the global agentic loop (~/.claude/agents/forge.md).
+# See docs/superpowers/specs/*loop-multi-repo-config*.
+
+# wiring
+repo_slug: sammyjdev/axon
+default_branch: master            # axon uses master, not main
+# Gate mirrors what CI actually enforces (router + resilience) and extends pytest
+# to the working area for the current backlog (store + scripts + cli + doctor).
+# tests/cli and tests/doctor were verified green (non-interactive, no skips) on
+# 2026-07-06 before being added here - see issue #60, which touches both dirs.
+# It does NOT run the full suite: tests/config and tests/benchmark carry
+# pre-existing failures that CI never gated (ci.yml only runs router+resilience).
+# See the "test-debt + expand CI" backlog item before widening further.
+gate_cmd: "ruff check src/axon/router src/axon/resilience tests/router tests/resilience && pytest tests/router tests/resilience tests/store tests/scripts tests/cli tests/doctor -q"
+setup_cmd: "pip install -e \".[dev]\""   # same as CI (ci.yml); shared venv already provisioned
+labels:
+  ready: agent:ready
+  blocked: agent:blocked
+
+# posture (axon is an internal context engine, not a customer-facing product)
+posture: internal
+risk_areas:
+  - restricted-context   # ctx=work; DENY_RESTRICTED_TOOL_WRITE (dec-109) - never bypass
+  - destructive-tools    # AXON_ALLOW_DESTRUCTIVE gate; default deny
+  - secrets              # .env / API keys - never commit
+  - chunker              # Java chunker is a release gate (D5) - do not weaken its tests
+  - migration            # relational backend cutover (dec-121); SQLite rollback must survive
+quality_rubric:
+  testability: true
+  scalability: true
+  progression: true
+
+# Notes for the loop operator (axon-specific):
+# - Worktrees are SAFE here: the root conftest.py inserts the worktree-relative
+#   src (no editable install), so per-worktree tests validate that worktree's code.
+# - pytest can HANG ON EXIT (unclosed asyncpg pool past the printed summary);
+#   wrap gate runs in a timeout and read the printed "N passed/failed".
+# - The full `pytest -q` is RED on master from pre-existing test debt (config mode
+#   default, benchmark, some hooks TTY+Windows cases) - that is NOT a regression
+#   and NOT an env leak; it is simply outside the CI gate. Do not treat it as a
+#   base failure; widen the gate only after the test-debt backlog item lands.
+#   (tests/doctor was moved out of this exclusion list on 2026-07-06 - it is
+#   green and now part of gate_cmd above.)

axon_context_mcp-0.1.1/.env.example

@@ -0,0 +1,107 @@
+# AXON environment template
+# Most users only need to review these values after `./setup.sh` creates `.env.local`.
+# The usual edits are: engine path, vault path, and any cloud API keys.
+
+# Required local paths
+AXON_ENGINE=~/dev/axon
+AXON_VAULT=~/vault
+
+# Setup/bootstrap mode. setup.sh persists the resolved mode into .env.local.
+# Supported values: full-local, hybrid-local, remote-infra, minimal.
+AXON_RUNTIME_MODE=full-local
+
+# Optional: point setup.sh at a remote Docker/Ollama host before running it.
+# setup.sh writes the matching service URLs into `.env.local` automatically.
+# AXON_INFRA_HOST=192.168.x.x
+
+# Routing profile: "free" (Groq + NVIDIA NIM free tiers) ou "paid"
+# (OpenRouter Claude D2 + Groq pago). FREE é o default — sem custo direto,
+# mas sujeito a rate limits dos provedores.
+AXON_PROVIDER_PROFILE=free
+
+# Chaves dos provedores selecionados pelo profile ativo.
+# FREE precisa: GROQ_API_KEY + NVIDIA_NIM_API_KEY
+# PAID precisa: OPENROUTER_API_KEY + GROQ_API_KEY (Groq pago)
+GROQ_API_KEY=your-groq-api-key
+NVIDIA_NIM_API_KEY=your-nvidia-nim-api-key
+OPENROUTER_API_KEY=your-openrouter-api-key
+
+# Anthropic API direta (opcional; profiles free/paid não usam)
+ANTHROPIC_API_KEY=your-anthropic-api-key
+
+# Core service defaults
+QDRANT_URL=http://localhost:6333
+REDIS_URL=redis://localhost:6379
+LANGFUSE_HOST=http://localhost:3000
+AXON_OLLAMA_LOCAL_HOST=http://127.0.0.1:11434
+AXON_OLLAMA_REMOTE_HOST=
+
+# Langfuse / local infra secrets
+LANGFUSE_NEXTAUTH_SECRET=change-me
+LANGFUSE_SALT=change-me
+POSTGRES_USER=axon
+POSTGRES_PASSWORD=change-me
+POSTGRES_DB=langfuse
+
+# Runtime defaults
+AXON_RTK_MAX_TOKENS=450
+AXON_CAVEMAN_MODEL=phi3:mini
+# Path to the rtkx binary. Leave unset to auto-resolve:
+# AXON_RTK_BIN -> ~/.axon/bin/rtkx (installed by `axon rtk-init`) -> PATH (rtkx, then rtk).
+# AXON_RTK_BIN=/custom/path/to/rtkx
+AXON_DAILY_BUDGET=5.0
+AXON_OPUS_BUDGET=2.0
+AXON_MAX_PRE_SEND_TOKENS=8000
+AXON_PROVIDER_ANTHROPIC=1
+AXON_PROVIDER_OPENROUTER=1
+# Ollama off por default — habilite explicitamente se tiver hardware adequado
+AXON_PROVIDER_OLLAMA=0
+# Override do modelo do classifier (vazio = usa default do profile ativo)
+# AXON_CLASSIFIER_CLOUD_MODEL=groq/llama-3.1-8b-instant
+AXON_CLASSIFIER_TIMEOUT=4.0
+AXON_POLICY_VERSION=2026-04-21
+# Validação de compliance OpenRouter (default off — habilite se exige
+# metadata zdr/retention/training_use em task.extra)
+AXON_OPENROUTER_COMPLIANCE=0
+
+# Rate limit por provider (vazio = sem limite). Defaults conservadores
+# pra free tier — margem sob os limites reais (Groq 30/min, NIM ~1000/dia).
+AXON_GROQ_MAX_RPM=25
+AXON_GROQ_MAX_RPD=13000
+AXON_NVIDIA_NIM_MAX_RPM=50
+AXON_NVIDIA_NIM_MAX_RPD=950
+# OpenRouter, Anthropic, Ollama: sem cap por default (pago/local)
+# AXON_OPENROUTER_MAX_RPM=
+# AXON_OPENROUTER_MAX_RPD=
+# AXON_ANTHROPIC_MAX_RPM=
+# AXON_ANTHROPIC_MAX_RPD=
+
+# Expansion
+AXON_EXPANSION_SOURCE_CATALOG=${AXON_ENGINE}/config/expansion_sources.json
+AXON_EXPANSION_ENABLED=true
+AXON_EXPANSION_MANUAL_ONLY=true
+AXON_EXPANSION_CONTEXTS=knowledge,career,personal
+AXON_EXPANSION_ALLOW_CLOUD=true
+AXON_EXPANSION_MONTHLY_BUDGET=4.0
+AXON_EXPANSION_SOFT_CAP=3.2
+AXON_EXPANSION_HARD_CAP=4.0
+
+# Platform-generated defaults that setup.sh refreshes
+AXON_PLATFORM=mac
+EMBEDDING_PROVIDERS=CoreMLExecutionProvider,CPUExecutionProvider
+OLLAMA_FLASH=false
+OLLAMA_MAX_LOADED_MODELS=1
+OLLAMA_MODEL_PRIMARY=gemma4:e4b
+OLLAMA_MODEL_KNOWLEDGE=gemma4:e4b
+OLLAMA_KEEP_ALIVE=10m
+OLLAMA_NUM_PARALLEL=2
+OLLAMA_HOST=http://localhost:11434
+
+# Compatibility / local defaults
+QDRANT_HOST=localhost
+QDRANT_PORT=6333
+REDIS_HOST=localhost
+REDIS_PORT=6379
+AXON_VECTOR_SIZE=384
+AXON_WORK_CTX=0
+SQLITE_PATH=./data/axon.db

axon_context_mcp-0.1.1/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,27 @@
+---
+name: Bug report
+about: Report something that doesn't work as expected
+title: ""
+labels: bug
+assignees: ""
+---
+
+**Describe the bug**
+A clear description of what's broken.
+
+**To reproduce**
+Steps to reproduce the behavior, ideally a minimal command sequence
+(`axon ...`).
+
+**Expected behavior**
+What you expected to happen instead.
+
+**Environment**
+- AXON version / commit: `axon --version`
+- OS:
+- Python version:
+- Provider profile (`AXON_PROVIDER_PROFILE`): free / paid
+
+**Logs / output**
+Paste relevant output from `axon doctor` or the failing command. Redact any
+API keys.

axon_context_mcp-0.1.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/sammyjdev/axon/security/advisories/new
+    about: Please report security vulnerabilities privately, not as a public issue.

axon_context_mcp-0.1.1/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,19 @@
+---
+name: Feature request
+about: Suggest an idea for AXON
+title: ""
+labels: enhancement
+assignees: ""
+---
+
+**Problem**
+What are you trying to do that AXON doesn't support today?
+
+**Proposed solution**
+What would you like to happen?
+
+**Alternatives considered**
+Any workarounds you're using today, or other approaches you considered.
+
+**Additional context**
+Anything else — related issues, links, screenshots.

axon_context_mcp-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,97 @@
+name: ci
+
+# dec-107 — validation strategy. Lint, compile, and router/resilience tests
+# under both provider profiles (free, paid). dec-106 defines the profile system.
+
+on:
+  pull_request:
+  push:
+    branches: [master, main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: ruff
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: install ruff
+        run: pip install "ruff>=0.4.0"
+      # TODO(dec-107): expand to `src/ tests/` once the existing lint debt
+      # outside router/resilience is cleared. Today the broader scope has
+      # 22 pre-existing UP/I001/F401/E501 findings. Tracked separately.
+      - name: ruff check (router + resilience)
+        run: ruff check src/axon/router src/axon/resilience tests/router tests/resilience
+
+  compile:
+    name: compileall
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: compileall src
+        run: python3 -m compileall -q src
+
+  test:
+    name: pytest (${{ matrix.profile }} / py${{ matrix.python }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.11", "3.12"]
+        profile: [free, paid]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - name: install project + dev deps
+        run: pip install -e ".[dev]"
+      - name: pytest router + resilience
+        env:
+          AXON_PROVIDER_PROFILE: ${{ matrix.profile }}
+        run: python3 -m pytest tests/router tests/resilience -q
+
+  profile-smoke:
+    name: profile import smoke (${{ matrix.profile }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    strategy:
+      fail-fast: false
+      matrix:
+        profile: [free, paid]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - name: install project
+        run: pip install -e .
+      - name: import and resolve profile
+        env:
+          AXON_PROVIDER_PROFILE: ${{ matrix.profile }}
+        run: |
+          python3 -c "
+          from axon.router.profiles import get_profile, available_profiles
+          from axon.router.engine import _MODEL_MAP, _COST_PER_1K, _PROFILE
+          assert _PROFILE.name == '${{ matrix.profile }}'
+          assert _MODEL_MAP, 'model map empty'
+          assert all(v for v in _MODEL_MAP.values()), 'unmapped task type'
+          print('profile:', _PROFILE.name)
+          print('models:', dict(_MODEL_MAP))
+          "

axon_context_mcp-0.1.1/.gitignore

@@ -0,0 +1,71 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.venv/
+venv/
+
+# Environment
+.env
+.env.local
+.env.*.local
+.env*.bak
+
+# Per-repo AXON state (context fallback file, generated by hooks)
+.axon/
+
+# Per-repo agent settings (MCP config is machine-local); track the loop config
+.claude/*
+!.claude/loop.yaml
+
+# Data (runtime volumes do docker-compose) — anchored to repo root so it does
+# not also swallow packaged data like src/axon/data/ (dec-116 #6).
+/data/*
+# Exception: commit the compression telemetry snapshot so the metrics in
+# docs/METRICS.md are reproducible from a fresh checkout.
+!/data/compression/
+/data/compression/*
+!/data/compression/stats.jsonl
+*.db
+*.sqlite
+*.sqlite3
+
+# Local article drafts
+docs/LINKEDIN_ARTICLE_NOTES.md
+
+# Logs
+*.log
+logs/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Benchmark outputs
+benchmarks/results/*.png
+
+# Build artifacts
+dist/
+
+# Machine-specific docker override (redirects qdrant/redis volumes to D:)
+docker-compose.override.yml
+
+# Subagent-driven-development scratch (briefs, ledger, review packages)
+.superpowers/
+
+# forge scratch (spec/tasks/validation artifacts, never tracked)
+.specs/
+
+# Coverage artifacts
+.coverage
+.coverage.*

axon_context_mcp-0.1.1/.rtk/filters.toml

@@ -0,0 +1,13 @@
+# Project-local RTK filters — commit this file with your repo.
+# Filters here override user-global and built-in filters.
+# Docs: https://github.com/rtk-ai/rtk#custom-filters
+schema_version = 1
+
+# Example: suppress build noise from a custom tool
+# [filters.my-tool]
+# description = "Compact my-tool output"
+# match_command = "^my-tool\\s+build"
+# strip_ansi = true
+# strip_lines_matching = ["^\\s*$", "^Downloading", "^Installing"]
+# max_lines = 30
+# on_empty = "my-tool: ok"

axon_context_mcp-0.1.1/AGENTS.md

@@ -0,0 +1 @@
+CLAUDE.md

axon_context_mcp-0.1.1/CLAUDE.md

@@ -0,0 +1,181 @@
+# AXON Agent Guide
+
+This is the canonical agent context file for contributors working in this
+repository. `AGENTS.md` points to this file.
+
+## Project Overview
+
+AXON is a self-hosted context engine for local knowledge retrieval,
+context compression, and agent-facing workflows through a CLI (`axon`) and MCP.
+
+The repository contains the engine and runtime code. User knowledge lives in an
+external Markdown vault, typically configured through:
+
+- `AXON_ENGINE=/path/to/axon`
+- `AXON_VAULT=~/vault`
+
+## Entry Points
+
+- [README.md](README.md): public project overview and quick start
+- [docs/VAULT_SETUP.md](docs/VAULT_SETUP.md): external vault bootstrap
+- [docs/USAGE_GUIDE.md](docs/USAGE_GUIDE.md): CLI workflows
+- [docs/ADR.md](docs/ADR.md): active architectural decisions
+- [docs/ARD.md](docs/ARD.md): active architectural requirements
+
+## Stable Architectural Decisions
+
+### D1: Data and engine stay separate
+
+- Vault data lives outside this repository.
+- Runtime code and configuration live in this repository.
+- Do not mix vault content into the engine tree.
+
+### D2: Task-based cloud routing
+
+D2 defines the **tiering shape** (trivial → mid → top). The concrete model per
+tier is selected by the active provider profile (see dec-106). The PAID profile
+preserves D2 verbatim via OpenRouter; the FREE profile substitutes equivalent
+free-tier models.
+
+| Task type | PAID profile (D2 verbatim) | FREE profile |
+| --- | --- | --- |
+| trivial/completion | `openrouter/anthropic/claude-haiku-4` | `groq/llama-3.1-8b-instant` |
+| code analysis | `openrouter/anthropic/claude-sonnet-4` | `groq/llama-3.3-70b-versatile` |
+| architecture/deep reasoning | `openrouter/anthropic/claude-opus-4` | `nvidia_nim/meta/llama-3.1-70b-instruct` |
+| fallback | trivial of the active profile | trivial of the active profile |
+
+Downgrade is task-type-driven (top→mid when Opus budget is exceeded; mid→bottom
+when daily budget is exceeded) and works identically under both profiles. See
+`docs/decisions/dec-106-routing-profiles.md`.
+
+### D3: Local Ollama defaults (opt-in)
+
+Ollama is **opt-in** as of dec-106 (`AXON_PROVIDER_OLLAMA=1`). When enabled,
+the supported models are:
+
+- `phi3:mini`: lightweight compression and local-first workflows
+- `gemma4:e4b`: local scoring and classification
+- `gemma4:26b`: heavier deep-suggestion workloads on larger hardware
+
+Default profiles (FREE/PAID) never route to Ollama; enable it explicitly for
+`ctx=work` or any other path that requires local-only execution.
+
+### D4: Single Postgres backend (dec-101 fully superseded by dec-121)
+
+dec-121 is **complete** (all three slices landed; ADR accepted 2026-06-29).
+Persistence is consolidated on a single PostgreSQL instance:
+
+- **Relational source-of-truth** (decisions/ADRs/sessions/graph nodes+edges/
+  file_index, plus FailureStore/OutcomeStore) lives in Postgres. SQLite is fully
+  retired — the SQLite repositories, `SessionStore`'s aiosqlite connection, the
+  SQL migrations, and the `aiosqlite` dependency are deleted.
+- **Vectors**: `pgvector` (Qdrant + mem0 dropped).
+- **Code-dependency call-graph**: the `dep:*` graph lives in the Postgres
+  `symbol_deps` table (Redis retired; rate limiter / circuit breaker are in-memory).
+- GLYPH keeps graph **retrieval** (dec-116/117 stand). Neo4j was evaluated and
+  dropped — see `docs/decisions/dec-101-revoke-d4-drop-neo4j.md`.
+
+Guards `tests/test_no_{qdrant,redis,sqlite}.py` keep the retired backends out. See
+`docs/decisions/dec-121-postgres-unified-storage.md` and the phase plans under
+`docs/superpowers/plans/`.
+
+### D5: Chunker quality is a release gate
+
+- The Java chunker is a high-risk subsystem.
+- Structure-aware chunking and fixture coverage must remain intact.
+- Do not weaken chunker tests to make implementation changes pass.
+
+## Recall ranking
+
+`recall_context` supports **opt-in soft supersession** (dec-115, default off): a
+stale decision is demoted (rank × 0.02), never dropped, when a newer decision in
+the same scope revises it. Detection = shared scope **and** a confirmed revision
+— a revision verb in the newer summary (EN/PT) or a near-duplicate
+(cosine ≥ `_NEAR_DUP_THRESHOLD` 0.93). Additive same-area work is intentionally
+*not* superseded (a flat cosine floor produced ~90% false positives on real
+data). Enable via `recall_context(..., enable_supersession=True,
+similarity=make_embedding_similarity(EmbedderEngine()))`; keep it off in
+production until reworded-revision recall is validated. See
+`docs/decisions/dec-115-supersession-ranking-penalty.md` and
+`docs/USAGE_GUIDE.md`.
+
+## Onboarding layers (do not conflate)
+
+Two separate, intentionally non-identical lists govern "which repos AXON knows
+about". Do **not** try to unify or sync them:
+
+- **Agent scope** — `~/.claude/axon/ROUTER.md` (global, synced dotfiles). The
+  **single source of truth** for which repos Claude should recall/capture in. Any
+  onboarded-repo list elsewhere (e.g. the integration plan/spec under
+  `docs/superpowers/`) only references this one.
+- **Index manifest** — `config/projects.json` (committed, read by
+  `src/axon/cli/pb.py` for batch indexing). Per-machine and **multi-machine by
+  design**: it carries absolute paths for the machine that authored it (e.g. macOS
+  `/Users/...`), so on another machine it is dormant and onboarding happens
+  per-repo via `axon init <path>`. Foreign paths here are expected, not stale.
+
+## Code Conventions
+
+- Python 3.11+ with type hints
+- Domain/data models (persisted or serialized) use Pydantic v2; internal
+  config and in-process value objects may use `dataclass`. Prefer either over
+  ad-hoc dicts. See `docs/decisions/dec-105-migrate-domain-models-to-pydantic.md`.
+- Prefer async for I/O-heavy paths
+- Add comments only for non-obvious constraints or rationale
+- Keep public examples and docs machine-agnostic
+- `SessionStore` must be initialized explicitly with `.init()`
+
+## Agent Rules
+
+- Start from tests when changing behavior.
+- Bugfixes should begin with a regression test when feasible.
+- Features should have testable acceptance criteria before implementation.
+- Do not silence failing tests or guardrails to make a change appear complete.
+- Prefer the smallest coherent change that satisfies the behavior.
+
+## Restricted Context Rules
+
+- `work` is a restricted context.
+- Never access restricted context implicitly.
+- Use explicit `ctx=work` only when the task really requires it.
+- Do not copy restricted or proprietary material into the repository or public
+  documentation.
+- Write/destructive MCP tools called with `ctx=work` are denied with
+  `DENY_RESTRICTED_TOOL_WRITE` (dec-109). Downgrade the ctx explicitly if
+  the action really belongs in a different context — never bypass the
+  gate.
+
+## Tool Risk and Audit
+
+- Every MCP tool carries a risk class (`read` / `write` / `destructive`)
+  enforced by `@traced_tool`. See ADR-013 / dec-109.
+- Destructive tools require `AXON_ALLOW_DESTRUCTIVE` truthy
+  (`1`/`true`/`yes`/`on`). The default is deny — do not paper over the
+  consent gate in tests or scripts.
+- `Decision.judged: bool` is the canonical "scored" flag. Never use
+  `validation_score == 0.0` as a sentinel for unscored decisions — that
+  conflates a legitimate clamped-to-zero score with the default and
+  causes re-judging on every push.
+
+## Safety Rules
+
+- Never commit credentials, tokens, `.env` files, or user data.
+- Never move vault content into the engine repository.
+- Never weaken isolation around restricted contexts as a shortcut.
+- Investigate failing tests, hooks, or checks instead of bypassing them.
+
+## Validation Defaults
+
+Use `rtk` where available. Typical validation commands:
+
+```bash
+rtk pytest tests/ -q
+rtk ruff check
+rtk python3 -m compileall src
+```
+
+## RTK Notes
+
+AXON is commonly used with RTK (Rust Token Killer) for compact command
+output. Prefix commands with `rtk` when possible; if no specialized filter is
+available, RTK passes the command through unchanged.

axon_context_mcp-0.1.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,50 @@
+# 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.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Focusing on what is best for the community
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and unwelcome sexual attention
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing standards of
+acceptable behavior and will take appropriate corrective action in response to
+any behavior deemed inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all project spaces (issues, pull requests,
+discussions) and when an individual is officially representing the project in
+public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the maintainers via a GitHub issue marked confidential or through
+GitHub's report-abuse form. All complaints will be reviewed and investigated
+promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the
+[Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

axon_context_mcp-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing to AXON
+
+Thanks for considering a contribution. AXON is an early-stage (Alpha) project;
+expect some rough edges and fast-moving internals.
+
+## Development setup
+
+```bash
+git clone https://github.com/sammyjdev/axon.git
+cd axon
+pip install -e ".[dev]"
+```
+
+## Before opening a PR
+
+```bash
+pytest tests/ -q
+ruff check
+python3 -m compileall src
+```
+
+All tests must pass. Fix `ruff` errors; warnings are at your discretion until
+the broader lint scope is enforced in CI (see `.github/workflows/ci.yml`).
+
+## Workflow
+
+- TDD is expected: a failing test before production code, a regression test
+  for bugfixes.
+- Keep changes surgical — match existing style, avoid drive-by refactors in
+  unrelated code.
+- Commit messages: `<type>: <description>` (`feat`, `fix`, `refactor`, `docs`,
+  `test`, `chore`, `perf`, `ci`).
+- Reference the architectural decisions under `docs/decisions/` (`dec-*.md`)
+  when a change touches an existing one; open a new one for decisions that
+  aren't obvious from the code.
+
+## Reporting bugs / requesting features
+
+Open a GitHub issue. Use the provided issue templates when available.
+
+## Reporting security issues
+
+See [SECURITY.md](SECURITY.md) — do not open a public issue for
+vulnerabilities.
+
+## Project structure
+
+See [CLAUDE.md](CLAUDE.md) (agent-facing) and
+[docs/PROJECT_OVERVIEW.md](docs/PROJECT_OVERVIEW.md) for a map of the
+subsystems, CLI surface, and MCP tools.