citadel-archive 0.1.0__tar.gz

citadel_archive-0.1.0/.env.example

@@ -0,0 +1,242 @@
+# Citadel wrapper config
+# Structured logging level: DEBUG, INFO, WARNING, ERROR, or CRITICAL.
+CITADEL_LOG_LEVEL=INFO
+# Retry policy for outbound calls (GitHub, Google Chat, LLM digesting).
+# Exponential backoff with full jitter; Retry-After headers are honored.
+CITADEL_RETRY_MAX_ATTEMPTS=3
+CITADEL_RETRY_BASE_DELAY_SECONDS=0.5
+CITADEL_RETRY_MAX_DELAY_SECONDS=8.0
+CITADEL_TENANT_ID=personal
+CITADEL_USER_ID=local
+CITADEL_ADMIN_KEY=
+CITADEL_WRITER_KEYS=
+CITADEL_READER_KEYS=
+CITADEL_ACCESS_STORE_PATH=/data/.citadel/access.json
+CITADEL_AUDIT_MAX_EVENTS=1000
+# Knowledge Conflict store (visible disagreements; never silently overwritten).
+CITADEL_CONFLICTS_STORE_PATH=/data/.citadel/conflicts.json
+CITADEL_CONFLICTS_MAX_RECORDS=500
+# Node cap for GET /api/mesh/graph (the real Cognee knowledge graph).
+CITADEL_MESH_GRAPH_MAX_NODES=200
+CITADEL_DEFAULT_DATASET=personal
+# Dataset used when a /search request omits "dataset" (e.g. masumi-network).
+# Leave empty to fall back to CITADEL_DEFAULT_DATASET and return a hint instead.
+CITADEL_SEARCH_DEFAULT_DATASET=masumi-network
+CITADEL_DEFAULT_SESSION=personal-session
+CITADEL_DEFAULT_TAGS=personal
+CITADEL_MIN_CHARS=3
+CITADEL_EXCLUDE_PATTERNS=.git/*,.venv/*,__pycache__/*,node_modules/*
+CITADEL_AUTO_IMPROVE=false
+CITADEL_BUILD_GLOBAL_CONTEXT_INDEX=false
+CITADEL_COGNEE_SEARCH_TYPE=CHUNKS
+
+# Hosted MCP (mounted at /mcp). Forwarded calls hit the API in-process.
+CITADEL_MCP_SELF_BASE_URL=http://127.0.0.1:8000
+# Optional: pin Host/Origin allow-lists to enable DNS-rebinding protection.
+# Leave empty for a token-authenticated public endpoint.
+CITADEL_MCP_ALLOWED_HOSTS=
+CITADEL_MCP_ALLOWED_ORIGINS=
+
+# Local stdio MCP wrapper config.
+CITADEL_HTTP_BASE_URL=http://localhost:8000
+CITADEL_MCP_ACCESS_TOKEN=
+CITADEL_MCP_DEFAULT_DATASET=masumi-network
+CITADEL_MCP_MAX_INGEST_BYTES=200000
+CITADEL_MCP_ALLOW_INSECURE_HTTP=false
+
+# Railway run mode: web, pipeline (full scheduled run: GitHub org sync,
+# skills refresh, self-improvement, backup mirror), evolve (6h self-evolving
+# cycle, ADR-0005 step 3), or the single jobs learning-agent/github-sync and
+# backup-mirror.
+CITADEL_RUN_MODE=web
+# Pipeline stage toggles. A failed stage never stops later stages; the run
+# exits nonzero only when every enabled stage fails.
+CITADEL_PIPELINE_GITHUB_SYNC_ENABLED=true
+CITADEL_PIPELINE_REPO_CONTENT_SYNC_ENABLED=true
+CITADEL_PIPELINE_SKILLS_REFRESH_ENABLED=true
+CITADEL_PIPELINE_BACKUP_MIRROR_ENABLED=true
+# Evolve cron stage toggles (CITADEL_RUN_MODE=evolve). Same fail-soft semantics
+# as the pipeline: a failed stage never stops later stages and the run exits
+# nonzero only when every enabled stage fails. The 6h cadence is an operator
+# Railway-cron step, not code. Chain: github sync -> repo-content sync ->
+# self-improve -> promotion -> cognify.
+CITADEL_EVOLVE_GITHUB_SYNC_ENABLED=true
+CITADEL_EVOLVE_REPO_CONTENT_SYNC_ENABLED=true
+CITADEL_EVOLVE_SELF_IMPROVE_ENABLED=true
+CITADEL_EVOLVE_PROMOTION_ENABLED=true
+CITADEL_EVOLVE_COGNIFY_ENABLED=true
+# Where the pipeline stores last-seen skill content hashes for change detection.
+CITADEL_SKILLS_STATE_PATH=/data/.citadel/skills_catalog.json
+
+# LLM-assisted chunking + enrichment in the Learning Process (OpenRouter).
+# Disabled by default; on any failure ingestion falls back to deterministic
+# paragraph chunking and never fails because of the LLM.
+CITADEL_LLM_ENRICHMENT_ENABLED=true
+# OpenRouter model for enrichment, self-improvement, and the digest default.
+# This path calls OpenRouter's HTTP API directly (not litellm), so it uses the
+# BARE OpenRouter id — do NOT add the openrouter/ prefix here (that is for LLM_MODEL).
+CITADEL_LLM_MODEL=deepseek/deepseek-v4-flash
+# Source material below this size is ingested as-is (chars).
+CITADEL_LLM_ENRICHMENT_THRESHOLD_CHARS=4000
+
+# Self-improvement loop (POST /api/learning-agent/optimize + pipeline stage).
+# Strictly bounded and additive: re-tags/summarizes recent ingests, never deletes.
+CITADEL_SELF_IMPROVE_ENABLED=false
+CITADEL_SELF_IMPROVE_MAX_ITEMS=10
+CITADEL_SELF_IMPROVE_DRY_RUN=false
+# Optional: run the cron stage through the web service instead of in-process.
+CITADEL_SELF_IMPROVE_ENDPOINT=
+CITADEL_SELF_IMPROVE_ACCESS_KEY=
+CITADEL_SELF_IMPROVE_TIMEOUT_SECONDS=600
+CITADEL_GITHUB_ORG=masumi-network
+CITADEL_GITHUB_SYNC_DATASET=masumi-network
+CITADEL_GITHUB_SYNC_SESSION=masumi-github-daily
+
+# Linear workspace sync (read-only fetch). Full workspace → Central
+# (masumi-network); assignee issues mirrored into seat Nodes.
+# A Linear personal API key with Read scope is sufficient (no Write/Admin).
+# Run via admin API, CITADEL_RUN_MODE=linear-sync, or Railway cron.
+CITADEL_LINEAR_API_KEY=
+CITADEL_LINEAR_SYNC_DATASET=masumi-network
+CITADEL_LINEAR_SYNC_SESSION=masumi-linear
+CITADEL_LINEAR_SYNC_MAX_ISSUES=200
+# Optional JSON map Linear user id → seat slug: {"user-uuid":"john"}
+CITADEL_LINEAR_USER_MAP=
+CITADEL_GITHUB_SYNC_STATE_PATH=/data/.citadel/github_sync_state.json
+CITADEL_GITHUB_SYNC_MAX_REPOS=100
+CITADEL_GITHUB_SYNC_MAX_EVENTS=50
+CITADEL_GITHUB_SYNC_MAX_COMMITS_PER_REPO=5
+CITADEL_GITHUB_SYNC_MAX_PULL_REQUESTS_PER_REPO=5
+CITADEL_GITHUB_SYNC_INCLUDE_COMMITS=true
+CITADEL_GITHUB_SYNC_RUN_IMPROVE=true
+CITADEL_GITHUB_SYNC_INGEST_UNCHANGED=true
+# Deep repository content sync (READMEs, skills, docs) for cognification.
+CITADEL_REPO_CONTENT_SYNC_ENABLED=true
+CITADEL_REPO_CONTENT_SYNC_DATASET=masumi-network
+CITADEL_REPO_CONTENT_SYNC_SESSION=masumi-repo-content
+CITADEL_REPO_CONTENT_SYNC_STATE_PATH=/data/.citadel/repo_content_sync_state.json
+CITADEL_REPO_CONTENT_SYNC_REPOS=sokosumi,Sokosumi-MCP,sokosumi-cli,sokosumi-docs
+CITADEL_REPO_CONTENT_SYNC_ROOT_PATHS=README.md,SKILL.md,CONTEXT.md
+CITADEL_REPO_CONTENT_SYNC_TREE_PREFIXES=skills/,content/docs/,docs/,plugins/
+CITADEL_REPO_CONTENT_SYNC_TREE_EXTENSIONS=.md,.mdx,.txt
+CITADEL_REPO_CONTENT_SYNC_MAX_FILES_PER_REPO=40
+CITADEL_REPO_CONTENT_SYNC_MAX_BYTES_PER_FILE=120000
+CITADEL_REPO_CONTENT_SYNC_RUN_IMPROVE=true
+# Run a Cognee improvement cycle after each teammate/agent contribution. Off by
+# default: contributions are single small writes and improve is expensive.
+CITADEL_CONTRIBUTE_RUN_IMPROVE=false
+# Private repositories are sensitive even when only metadata is fetched.
+# Keep this explicit, and prefer allowlists for private repo monitoring.
+CITADEL_GITHUB_SYNC_INCLUDE_PRIVATE=true
+CITADEL_GITHUB_SYNC_REPO_ALLOWLIST=
+CITADEL_GITHUB_SYNC_REPO_DENYLIST=
+CITADEL_GITHUB_SYNC_SECURITY_SCAN_ENABLED=true
+CITADEL_GITHUB_SYNC_SECURITY_BLOCK_SEVERITY=high
+GITHUB_TOKEN=
+
+# GitHub PR-merge webhook -> non-blocking org re-ingest (ADR-0005 step 3).
+# Disabled by default: POST /api/webhooks/github returns 404 until enabled. When
+# enabled, the raw body is verified against X-Hub-Signature-256 (HMAC-SHA256
+# keyed by the secret) BEFORE parsing; a missing/invalid signature is rejected
+# with 401. Only a closed+merged pull_request triggers work (202); everything
+# else is acknowledged with 204. Set the SAME secret in the GitHub webhook UI.
+CITADEL_GITHUB_WEBHOOK_ENABLED=false
+CITADEL_GITHUB_WEBHOOK_SECRET=
+
+# Content/secret gate on EVERY write path (ADR-0005 step 1): /ingest,
+# /api/contribute, Obsidian sync, autosync, and MCP writers all funnel through
+# the service-layer ingest gate. A finding at or above the block severity is
+# refused (HTTP 422) and audited; the secret never reaches the vault.
+CITADEL_CONTENT_SCAN_ENABLED=true
+CITADEL_CONTENT_SCAN_BLOCK_SEVERITY=high
+
+# Selective promotion of seat-node content to Central (ADR-0005 step 2).
+# Opt-in: when enabled, POST /api/promote/run enumerates a seat node, classifies
+# each item for org-relevance + sensitivity (secret scan + LLM), and promotes
+# qualifying items (relevant AND not sensitive AND secret-clean AND
+# score >= threshold) via the org-ready dual-write. dry_run defaults TRUE
+# (propose only, write nothing); a human sets dry_run=false to actually promote.
+CITADEL_PROMOTION_ENABLED=false
+# Default dry-run for the evolve cron's promotion stage (propose, write nothing).
+# Set false to let the 6h evolve cron actually promote qualifying items.
+CITADEL_PROMOTION_DRY_RUN=true
+CITADEL_PROMOTION_RELEVANCE_THRESHOLD=0.7
+CITADEL_PROMOTION_MAX_ITEMS=20
+
+# Organization Update Digest for the learning-agent cron.
+CITADEL_ORG_DIGEST_ENABLED=true
+CITADEL_ORG_DIGEST_WINDOW_HOURS=24
+CITADEL_ORG_DIGEST_MAX_ITEMS=6
+CITADEL_ORG_DIGEST_LLM_ENABLED=true
+CITADEL_ORG_DIGEST_POST_ON_NO_UPDATES=false
+# Scheduled cron runs post by default and hide the raw message body from logs.
+# Manual API/CLI runs preview only unless post_to_chat/--post-to-chat is set.
+CITADEL_ORG_DIGEST_POST_TO_CHAT=true
+CITADEL_ORG_DIGEST_INCLUDE_PREVIEW_IN_CRON_OUTPUT=false
+# Cron stdout mode: summary, none, or full. Do not use full for private repos.
+CITADEL_GITHUB_SYNC_OUTPUT_MODE=summary
+# External LLM digesting is disabled for private repo metadata unless explicitly allowed.
+CITADEL_ORG_DIGEST_LLM_ALLOW_PRIVATE=false
+
+# Google Chat outbound delivery. Store the service account JSON as a Railway
+# secret. Do not commit real service account JSON or Google Chat space IDs.
+CITADEL_GOOGLE_CHAT_ENABLED=false
+CITADEL_GOOGLE_CHAT_SPACE_NAME=
+CITADEL_GOOGLE_CHAT_SERVICE_ACCOUNT_JSON=
+CITADEL_GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=
+CITADEL_GOOGLE_CHAT_THREAD_KEY=citadel-org-digest
+CITADEL_GOOGLE_CHAT_MESSAGE_PREFIX=citadel-org-digest
+CITADEL_GOOGLE_CHAT_MAX_MESSAGE_BYTES=30000
+CITADEL_GOOGLE_CHAT_TIMEOUT_SECONDS=20
+CITADEL_GOOGLE_CHAT_RETRY_COUNT=2
+
+# Vault Backup Mirror (private GitHub repo; manifest export only).
+CITADEL_BACKUP_MIRROR_REPO=masumi-network/Vault-Backup-Mirror
+CITADEL_BACKUP_MIRROR_ENABLED=false
+CITADEL_BACKUP_MIRROR_PUSH_ENABLED=false
+CITADEL_BACKUP_MIRROR_BRANCH=main
+CITADEL_BACKUP_MIRROR_ROOT_PATH=/data/.citadel/backup_mirror
+CITADEL_BACKUP_MIRROR_DRY_RUN=true
+CITADEL_BACKUP_MIRROR_ACCESS_KEY=
+CITADEL_BACKUP_MIRROR_TOKEN=
+
+# Local only. Railway sets PORT automatically.
+PORT=8000
+
+# Cognee passes these through from the process environment.
+LLM_API_KEY=
+OPENROUTER_API_KEY=
+LLM_PROVIDER=custom
+# Cognee routes through litellm, so this needs the openrouter/ prefix. A bare id
+# (e.g. "google/gemini-2.5-flash") fails with litellm "LLM Provider NOT provided".
+LLM_MODEL=openrouter/deepseek/deepseek-v4-flash
+LLM_ENDPOINT=https://openrouter.ai/api/v1
+COGNEE_SKIP_CONNECTION_TEST=true
+# Single-tenant: keep cognee's per-dataset/per-user graph partitioning OFF so cognify
+# and graph reads share ONE global Kuzu graph. Left unset, cognee enables it
+# automatically for kuzu+pgvector, which strands the built graph in a per-dataset
+# .pkl the org-wide mesh read never resolves (graph reads 0 despite a built graph).
+ENABLE_BACKEND_ACCESS_CONTROL=false
+EMBEDDING_PROVIDER=fastembed
+EMBEDDING_MODEL=BAAI/bge-small-en-v1.5
+EMBEDDING_DIMENSIONS=384
+
+# Railway/Postgres examples. Bind DATABASE_URL from the Railway Postgres service.
+DATABASE_URL=
+DB_PROVIDER=postgres
+DB_HOST=
+DB_PORT=5432
+DB_NAME=
+DB_USERNAME=
+DB_PASSWORD=
+VECTOR_DB_PROVIDER=pgvector
+# Optional overrides. When VECTOR_DB_PROVIDER=pgvector, Citadel derives these from DB_*
+# if they are not set explicitly.
+VECTOR_DB_HOST=
+VECTOR_DB_PORT=
+VECTOR_DB_NAME=
+VECTOR_DB_USERNAME=
+VECTOR_DB_PASSWORD=
+GRAPH_DATABASE_PROVIDER=kuzu
+SYSTEM_ROOT_DIRECTORY=/data/.cognee_system
+DATA_ROOT_DIRECTORY=/data/.data_storage

citadel_archive-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,47 @@
+name: Publish to PyPI
+
+# Publishes `citadel-archive` to PyPI on a version tag (e.g. v0.1.0) using
+# PyPI Trusted Publishing (OIDC) — no API tokens are stored anywhere.
+# One-time setup is documented in PUBLISHING.md.
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build sdist + wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Check metadata
+        run: |
+          python -m pip install --upgrade twine
+          python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # required for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

citadel_archive-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+.DS_Store
+.env
+.env.*
+!.env.example
+.venv/
+node_modules/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+.citadel/
+.claude/
+.cognee_system/
+.data_storage/
+.cognee_cache/
+logs/
+.brand-preview/

citadel_archive-0.1.0/.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "citadel": {
+      "type": "http",
+      "url": "https://citadel-archive-production.up.railway.app/mcp/",
+      "headers": {
+        "Authorization": "Bearer ${CITADEL_MCP_ACCESS_TOKEN}"
+      }
+    }
+  }
+}

citadel_archive-0.1.0/.mcp.json.example

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "citadel": {
+      "type": "http",
+      "url": "https://citadel-archive-production.up.railway.app/mcp",
+      "headers": {
+        "Authorization": "Bearer ${CITADEL_MCP_ACCESS_TOKEN}"
+      }
+    }
+  }
+}

citadel_archive-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

citadel_archive-0.1.0/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to `citadel-archive` are documented here. Format follows
+[Keep a Changelog](https://keepachangelog.com/); this project uses
+[Semantic Versioning](https://semver.org/).
+
+## [0.1.0] — 2026-06-27
+
+First published release. Ships the lightweight teammate CLI alongside the
+self-hosted Organization Vault server.
+
+### Added
+
+- **`citadel onboard`** — one-command, idempotent teammate setup: writes the
+  seat token to your shell rc (masked, env-only), installs the git pre-push and
+  Claude Code `SessionEnd` autosync hooks, adds the Citadel MCP server to
+  `.mcp.json`, and offers Approved Capture Roots. Self-contained — no vendored
+  skill directory required.
+- **`citadel status`** — connection + identity + local-setup health check
+  (Node `/healthz`, `/api/session` whoami, search smoke, hooks/MCP/capture
+  roots). `--json` for AI agents; exits non-zero when not connected.
+- **`citadel tui`** — live terminal dashboard (optional `[tui]` extra).
+- **`citadel setup` / `citadel capture`** — declare Approved Capture Roots
+  (`~/.citadel/capture.json`) with Capture Root Tags (`personal` / `org-work`),
+  and POST per-root summaries to your Node.
+- **Bundled autosync hooks** (`kb.hooks.sync_push`, `kb.hooks.sync_session`) —
+  stdlib-only, fail-silent, HTTPS-only, personal-by-default; installed by
+  `citadel onboard` and runnable as `python -m kb.hooks.*`.
+- Server **Capture Policy** baseline API + admin UI; seat **Node Write Policy**
+  enforced on all HTTP + MCP write paths.
+
+### Packaging
+
+- Distribution renamed to **`citadel-archive`** (the installed command stays
+  `citadel`). Base install is a lightweight client (`python-dotenv` only); the
+  server stack is the **`[server]`** extra and the dashboard the **`[tui]`**
+  extra. Importing the client never pulls the server stack (guarded by test).
+- PyPI **Trusted Publishing** workflow (`.github/workflows/publish.yml`) — tag
+  `v*` to build + publish, no stored tokens. See `PUBLISHING.md`.
+
+### Security
+
+- `post_capture` / hooks enforce HTTPS-only and refuse redirects (the seat
+  Bearer token is never re-sent to another host); payloads are size-capped.
+- The seat token lives in exactly one place (the shell rc); `.mcp.json`
+  references it as `${CITADEL_MCP_ACCESS_TOKEN}` and it is never echoed.
+- The pre-push allowlist fails **closed** on a corrupt config.
+
+[0.1.0]: https://github.com/masumi-network/Citadel-Archive/releases/tag/v0.1.0