cfgit 0.1.0__py3-none-any.whl

cfgit-0.1.0.dist-info/METADATA

@@ -0,0 +1,744 @@
+Metadata-Version: 2.4
+Name: cfgit
+Version: 0.1.0
+Summary: Git-style history, diff, drift detection, and rollback for live database records without migrating or owning your datastore
+Project-URL: Homepage, https://github.com/AusafMo/cfgit
+Project-URL: Repository, https://github.com/AusafMo/cfgit
+Project-URL: Issues, https://github.com/AusafMo/cfgit/issues
+Project-URL: Documentation, https://github.com/AusafMo/cfgit#readme
+Author: Mohammad Ausaf
+License:                                  Apache License
+                                   Version 2.0, January 2004
+                                http://www.apache.org/licenses/
+        
+           TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+        
+           1. Definitions.
+        
+              "License" shall mean the terms and conditions for use, reproduction,
+              and distribution as defined by Sections 1 through 9 of this document.
+        
+              "Licensor" shall mean the copyright owner or entity authorized by
+              the copyright owner that is granting the License.
+        
+              "Legal Entity" shall mean the union of the acting entity and all
+              other entities that control, are controlled by, or are under common
+              control with that entity. For the purposes of this definition,
+              "control" means (i) the power, direct or indirect, to cause the
+              direction or management of such entity, whether by contract or
+              otherwise, or (ii) ownership of fifty percent (50%) or more of the
+              outstanding shares, or (iii) beneficial ownership of such entity.
+        
+              "You" (or "Your") shall mean an individual or Legal Entity
+              exercising permissions granted by this License.
+        
+              "Source" form shall mean the preferred form for making modifications,
+              including but not limited to software source code, documentation
+              source, and configuration files.
+        
+              "Object" form shall mean any form resulting from mechanical
+              transformation or translation of a Source form, including but
+              not limited to compiled object code, generated documentation,
+              and conversions to other media types.
+        
+              "Work" shall mean the work of authorship, whether in Source or
+              Object form, made available under the License, as indicated by a
+              copyright notice that is included in or attached to the work
+              (an example is provided in the Appendix below).
+        
+              "Derivative Works" shall mean any work, whether in Source or Object
+              form, that is based on (or derived from) the Work and for which the
+              editorial revisions, annotations, elaborations, or other modifications
+              represent, as a whole, an original work of authorship. For the purposes
+              of this License, Derivative Works shall not include works that remain
+              separable from, or merely link (or bind by name) to the interfaces of,
+              the Work and Derivative Works thereof.
+        
+              "Contribution" shall mean any work of authorship, including
+              the original version of the Work and any modifications or additions
+              to that Work or Derivative Works thereof, that is intentionally
+              submitted to Licensor for inclusion in the Work by the copyright owner
+              or by an individual or Legal Entity authorized to submit on behalf of
+              the copyright owner. For the purposes of this definition, "submitted"
+              means any form of electronic, verbal, or written communication sent
+              to the Licensor or its representatives, including but not limited to
+              communication on electronic mailing lists, source code control systems,
+              and issue tracking systems that are managed by, or on behalf of, the
+              Licensor for the purpose of discussing and improving the Work, but
+              excluding communication that is conspicuously marked or otherwise
+              designated in writing by the copyright owner as "Not a Contribution."
+        
+              "Contributor" shall mean Licensor and any individual or Legal Entity
+              on behalf of whom a Contribution has been received by Licensor and
+              subsequently incorporated within the Work.
+        
+           2. Grant of Copyright License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              copyright license to reproduce, prepare Derivative Works of,
+              publicly display, publicly perform, sublicense, and distribute the
+              Work and such Derivative Works in Source or Object form.
+        
+           3. Grant of Patent License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              (except as stated in this section) patent license to make, have made,
+              use, offer to sell, sell, import, and otherwise transfer the Work,
+              where such license applies only to those patent claims licensable
+              by such Contributor that are necessarily infringed by their
+              Contribution(s) alone or by combination of their Contribution(s)
+              with the Work to which such Contribution(s) was submitted. If You
+              institute patent litigation against any entity (including a
+              cross-claim or counterclaim in a lawsuit) alleging that the Work
+              or a Contribution incorporated within the Work constitutes direct
+              or contributory patent infringement, then any patent licenses
+              granted to You under this License for that Work shall terminate
+              as of the date such litigation is filed.
+        
+           4. Redistribution. You may reproduce and distribute copies of the
+              Work or Derivative Works thereof in any medium, with or without
+              modifications, and in Source or Object form, provided that You
+              meet the following conditions:
+        
+              (a) You must give any other recipients of the Work or
+                  Derivative Works a copy of this License; and
+        
+              (b) You must cause any modified files to carry prominent notices
+                  stating that You changed the files; and
+        
+              (c) You must retain, in the Source form of any Derivative Works
+                  that You distribute, all copyright, patent, trademark, and
+                  attribution notices from the Source form of the Work,
+                  excluding those notices that do not pertain to any part of
+                  the Derivative Works; and
+        
+              (d) If the Work includes a "NOTICE" text file as part of its
+                  distribution, then any Derivative Works that You distribute must
+                  include a readable copy of the attribution notices contained
+                  within such NOTICE file, excluding those notices that do not
+                  pertain to any part of the Derivative Works, in at least one
+                  of the following places: within a NOTICE text file distributed
+                  as part of the Derivative Works; within the Source form or
+                  documentation, if provided along with the Derivative Works; or,
+                  within a display generated by the Derivative Works, if and
+                  wherever such third-party notices normally appear. The contents
+                  of the NOTICE file are for informational purposes only and
+                  do not modify the License. You may add Your own attribution
+                  notices within Derivative Works that You distribute, alongside
+                  or as an addendum to the NOTICE text from the Work, provided
+                  that such additional attribution notices cannot be construed
+                  as modifying the License.
+        
+              You may add Your own copyright statement to Your modifications and
+              may provide additional or different license terms and conditions
+              for use, reproduction, or distribution of Your modifications, or
+              for any such Derivative Works as a whole, provided Your use,
+              reproduction, and distribution of the Work otherwise complies with
+              the conditions stated in this License.
+        
+           5. Submission of Contributions. Unless You explicitly state otherwise,
+              any Contribution intentionally submitted for inclusion in the Work
+              by You to the Licensor shall be under the terms and conditions of
+              this License, without any additional terms or conditions.
+              Notwithstanding the above, nothing herein shall supersede or modify
+              the terms of any separate license agreement you may have executed
+              with Licensor regarding such Contributions.
+        
+           6. Trademarks. This License does not grant permission to use the trade
+              names, trademarks, service marks, or product names of the Licensor,
+              except as required for reasonable and customary use in describing the
+              origin of the Work and reproducing the content of the NOTICE file.
+        
+           7. Disclaimer of Warranty. Unless required by applicable law or
+              agreed to in writing, Licensor provides the Work (and each
+              Contributor provides its Contributions) on an "AS IS" BASIS,
+              WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+              implied, including, without limitation, any warranties or conditions
+              of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+              PARTICULAR PURPOSE. You are solely responsible for determining the
+              appropriateness of using or redistributing the Work and assume any
+              risks associated with Your exercise of permissions under this License.
+        
+           8. Limitation of Liability. In no event and under no legal theory,
+              whether in tort (including negligence), contract, or otherwise,
+              unless required by applicable law (such as deliberate and grossly
+              negligent acts) or agreed to in writing, shall any Contributor be
+              liable to You for damages, including any direct, indirect, special,
+              incidental, or consequential damages of any character arising as a
+              result of this License or out of the use or inability to use the
+              Work (including but not limited to damages for loss of goodwill,
+              work stoppage, computer failure or malfunction, or any and all
+              other commercial damages or losses), even if such Contributor
+              has been advised of the possibility of such damages.
+        
+           9. Accepting Warranty or Additional Liability. While redistributing
+              the Work or Derivative Works thereof, You may choose to offer,
+              and charge a fee for, acceptance of support, warranty, indemnity,
+              or other liability obligations and/or rights consistent with this
+              License. However, in accepting such obligations, You may act only
+              on Your own behalf and on Your sole responsibility, not on behalf
+              of any other Contributor, and only if You agree to indemnify,
+              defend, and hold each Contributor harmless for any liability
+              incurred by, or claims asserted against, such Contributor by reason
+              of your accepting any such warranty or additional liability.
+        
+           END OF TERMS AND CONDITIONS
+        
+           APPENDIX: How to apply the Apache License to your work.
+        
+              To apply the Apache License to your work, attach the following
+              boilerplate notice, with the fields enclosed by brackets "[]"
+              replaced with your own identifying information. (Don't include
+              the brackets!)  The text should be enclosed in the appropriate
+              comment syntax for the file format. We also recommend that a
+              file or class name and description of purpose be included on the
+              same "printed page" as the copyright notice for easier
+              identification within third-party archives.
+        
+           Copyright 2026 Mohammad Ausaf
+        
+           Licensed under the Apache License, Version 2.0 (the "License");
+           you may not use this file except in compliance with the License.
+           You may obtain a copy of the License at
+        
+               http://www.apache.org/licenses/LICENSE-2.0
+        
+           Unless required by applicable law or agreed to in writing, software
+           distributed under the License is distributed on an "AS IS" BASIS,
+           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+           See the License for the specific language governing permissions and
+           limitations under the License.
+License-File: LICENSE
+License-File: NOTICE
+Keywords: agents,configuration,database,database-versioning,datastore,drift-detection,mcp,mongodb,postgres,rollback,version-control
+Requires-Python: >=3.11
+Requires-Dist: tomli; python_version < '3.11'
+Provides-Extra: cli
+Requires-Dist: click>=8.1; extra == 'cli'
+Requires-Dist: rich>=13.0; extra == 'cli'
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: impact
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == 'mcp'
+Provides-Extra: mongo
+Requires-Dist: pymongo>=4.6; extra == 'mongo'
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.2; extra == 'postgres'
+Description-Content-Type: text/markdown
+
+# cfgit
+
+Non-custodial version control for live datastore records.
+
+A clean tool for dirty workflows. Git that does not make you move in.
+
+cfgit gives git-shaped history, diff, rollback, tags, and drift reconciliation to
+records that already live in your database. Your application keeps reading the
+same database. Your scripts and admin tools can still write it. cfgit sits beside
+the store, records what changed, and refuses to clobber changes it did not record.
+
+<p align="center">
+  <img src="docs/screenshots/01-diff.png" alt="Side-by-side line diff of a live agent config, with a sticky field header and collapsed context" width="32%" />
+  <img src="docs/screenshots/02-impact.png" alt="System-impact panel: deterministic facts plus opt-in LLM narration of what the change does downstream" width="32%" />
+  <img src="docs/screenshots/03-scoped-impact.png" alt="Scoped impact: select records on the left and reason the change against only those" width="32%" />
+</p>
+
+<p align="center">
+  <sub>Line-aligned diff of a live record &nbsp;·&nbsp; system-impact panel &nbsp;·&nbsp; impact scoped to the records you select &nbsp;(demo data)</sub>
+</p>
+
+## Why cfgit exists
+
+Many teams keep runtime behavior in live database records: model routing, agent
+prompts, provider settings, pricing tables, policy config, workflow definitions,
+feature controls, and other control-plane data. These records are often edited by
+people, scripts, admin APIs, and AI coding agents. The edits take effect
+immediately, but the workflow usually lacks the things engineers expect from code:
+
+- a useful history
+- a readable diff
+- a safe commit path
+- rollback to a known good point
+- a way to see when someone changed the database outside the tool
+
+Existing "git for data" tools usually solve a different problem: they want to
+own the database or sit in front of storage. cfgit is for the case where you
+cannot move the data and cannot put a gateway in the runtime path.
+
+## Core idea
+
+cfgit versions opaque JSON records identified by a stable id. It stores history
+beside the live datastore, not inside your application code and not in a hosted
+prompt registry.
+
+The important state is drift:
+
+- `cfg status` detects live records that changed outside cfgit.
+- `cfg diff <record> =HEAD =live` shows what changed.
+- `cfg adopt <record>` folds that out-of-band change into history.
+- `cfg commit` refuses to overwrite un-adopted drift.
+
+That drift reconciliation is the main reason cfgit exists.
+
+## Status
+
+cfgit is pre-1.0 software. The current implementation includes:
+
+- CLI with JSON output
+- MongoDB adapter
+- Postgres adapter
+- local author permission checks
+- per-environment identity modes with hashed token or DB-principal verification
+- opt-in branch and PR workflow for draft changes before runtime merge
+- system restore by tag or timestamp
+- localhost web UI
+- MCP server
+- portable Codex or Claude Code skill
+- optional `cfgit-impact` plugin for deterministic impact summaries and opt-in LLM narration
+
+The engine is intentionally DB-neutral. Mongo and Postgres are the first two
+adapters to prove the storage seam.
+
+## When to use cfgit
+
+Good fit:
+
+- control-plane collections or tables
+- low to moderate record counts
+- records edited by a small team or agents
+- changes where "who changed what and why" matters
+- data where rollback to a known good state is a real operation
+
+Examples:
+
+- agent configs
+- model routing records
+- provider templates
+- pricing or policy config
+- workflow definitions
+- feature or runtime behavior config
+
+Bad fit:
+
+- user-generated content
+- events, logs, analytics, metrics
+- high-write transactional tables
+- append-only data
+- rows written by traffic rather than curated by people
+
+cfgit stores full document versions. It is not a warehouse, event log, backup
+system, or schema migration tool.
+
+## Install
+
+From a checkout:
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+pip install -e '.[mongo,postgres,mcp,dev]'
+pip install -e plugins/cfg_impact
+```
+
+Minimal install for Mongo only:
+
+```bash
+pip install -e '.[mongo]'
+```
+
+Minimal install for Postgres only:
+
+```bash
+pip install -e '.[postgres]'
+```
+
+## Quick start
+
+Create `.cfg.toml` in the repo or working directory where you want to operate:
+
+```toml
+[project]
+name = "runtime-control-plane"
+
+[history]
+history_collection = "config_history"
+heads_collection = "config_heads"
+
+[branches]
+enabled = false
+refs_collection = "cfgit_refs"
+default_branch = "main"
+
+[[collection]]
+name = "agent_configs"
+id_field = "config_id"
+live_when = { is_active = true }
+ignore_fields = ["_id", "is_active", "updated_at", "updated_by"]
+secret_fields = []
+
+[env.dev]
+database = "mongo"
+uri = "env:DEV_MONGODB_URI"
+db = "my-dev-db"
+needs_approval = false
+
+[env.dev.identity]
+mode = "open"
+
+[env.dev.permissions]
+mode = "open"
+admins = []
+writers = []
+admin_actions = ["restore_system"]
+```
+
+You can define multiple `[env.<name>]` blocks, but one cfgit command opens one
+env at a time:
+
+```bash
+cfg --env dev status
+cfg --env prod log agent_configs:agent_planner
+```
+
+Keep each physical history store under one stable env name. If the same database
+is later addressed as a different env, cfgit will report that history exists
+under the original env instead of returning an empty log.
+
+Point it at a local or staging database first:
+
+```bash
+export DEV_MONGODB_URI='mongodb://localhost:27017/?replicaSet=rs0'
+cfg init
+cfg doctor
+cfg import --all -m "initial import"
+cfg status
+```
+
+`cfg doctor` is read-only. Run it before the first import for a new database or
+`.cfg.toml`; it reports secret-deny matches, large fields, and live-rule/key
+issues in one pass, with paste-ready `secret_fields` and `ignore_fields`
+suggestions.
+
+Check drift:
+
+```bash
+cfg status
+cfg diff agent_configs:agent_planner =HEAD =live
+```
+
+Commit a full JSON document:
+
+```bash
+cfg commit agent_configs:agent_planner --from planner.json -m "tune planner routing"
+```
+
+Commit multiple records as one batch intent:
+
+```json
+[
+  {"record": "agent_configs:planner", "doc": {"config_id": "planner", "model": "fast"}},
+  {"record": "modelgarden_models:openai/gpt-4o-mini", "doc": {"model_path": "openai/gpt-4o-mini"}}
+]
+```
+
+```bash
+cfg commit --bulk-from batch.json -m "switch planner routing"
+```
+
+Bulk commit preflights the whole batch before writing. If any target has
+un-adopted drift, is missing, duplicates another target, or trips the secret
+policy, cfgit applies none of the batch.
+
+Draft changes on a branch before mutating runtime:
+
+```bash
+cfg branch create router-test --from main
+cfg --branch router-test commit agent_configs:agent_planner --from planner.json -m "try router change"
+cfg diff main..router-test
+cfg pr create --base main --head router-test -m "review router change"
+cfg pr merge <pr-id>
+```
+
+Branching is opt-in with `[branches] enabled = true`. `branch`, branch commits,
+branch diff, and PR creation write only cfgit draft/review refs. The only branch
+command that mutates runtime is `cfg pr merge`, and it refuses stale main heads
+or un-adopted live drift.
+
+`commit`, `import`, and `adopt` scan the would-be-stored document for secret-like
+field names and values from `[secrets]`. Fields listed in `secret_fields` are
+stripped before history. Use `--allow-secret` only for intentional fixtures or
+known false positives; cfgit records the override in history metadata.
+
+Adopt an out-of-band database write:
+
+```bash
+cfg adopt agent_configs:agent_planner -m "adopt admin console edit"
+```
+
+Tag and restore:
+
+```bash
+cfg tag june7-good
+cfg restore --tag june7-good --dry-run -m "preview rollback"
+cfg restore --tag june7-good -m "restore known good state"
+```
+
+Open the local UI:
+
+```bash
+cfg ui
+```
+
+Run the MCP server:
+
+```bash
+cfg-mcp
+```
+
+## Record syntax
+
+Records are addressed as:
+
+```text
+collection:id
+```
+
+Examples:
+
+```text
+agent_configs:agent_planner
+modelgarden_models:openai/gpt-4o-mini
+```
+
+The collection and id field are configured in `.cfg.toml`.
+
+## Commands
+
+Common commands:
+
+```bash
+cfg init
+cfg doctor [record]
+cfg import --all -m "initial import"
+cfg status [record]
+cfg diff <record> [from] [to]
+cfg impact <record> [from] [to]
+cfg commit <record> --from <file.json> -m "message"
+cfg commit --bulk-from <batch.json> -m "message"
+cfg branch list
+cfg branch create <name> --from main
+cfg branch delete <name>
+cfg switch <name>
+cfg --branch <name> commit <record> --from <file.json> -m "message"
+cfg --branch <name> commit --bulk-from <batch.json> -m "message"
+cfg diff main..<branch>
+cfg --branch <branch> log
+cfg pr create --base main --head <branch> -m "message"
+cfg pr list
+cfg pr show <id>
+cfg pr close <id>
+cfg pr merge <id>
+cfg log <record>
+cfg show <record> <ref>
+cfg adopt <record> -m "message"
+cfg adopt --all -m "message"
+cfg tag <name>
+cfg restore <record> <ref> -m "message"
+cfg restore --as-of <date> --dry-run -m "message"
+cfg restore --tag <name> --dry-run -m "message"
+cfg fsck
+cfg whoami
+cfg ui
+```
+
+Every command supports `--json` for scripts and agents.
+
+Refs:
+
+- `=HEAD` or `HEAD`: last cfgit-recorded version
+- `=live` or `live`: current live database record
+- `@<seq>`: history entry number
+- `<oid-prefix>`: content hash prefix
+- `tag:<name>`: tagged version
+
+## Local UI
+
+`cfg ui` starts a localhost-only web UI over the same action layer as the CLI and
+MCP server. It reads like a git client: a collection-and-record tree on the left,
+a commit-graph history rail, and a line-aligned side-by-side diff that collapses
+unchanged context (expandable in place) and keeps the field name pinned while you
+scroll. It can run status, diff, impact, commit, branch draft commits, PR open
+and merge, log, show, adopt, restore, tag, init, import, and fsck, and ships
+dark and light themes.
+
+By default it binds to `127.0.0.1:8765` and tries the next free ports if needed:
+
+```bash
+cfg ui
+cfg ui --port 9000 --no-open
+```
+
+If you omit `--port`, cfgit will try the next free local ports. If you pass
+`--port` explicitly, cfgit treats that port as intentional and fails if it is
+already in use.
+
+## MCP and agent usage
+
+The MCP server exposes the same operations with a uniform envelope:
+
+```json
+{
+  "status": "ok",
+  "code": 0,
+  "message": "",
+  "data": {}
+}
+```
+
+Tools include:
+
+- `cfg_status`
+- `cfg_doctor`
+- `cfg_diff`
+- `cfg_impact`
+- `cfg_commit`
+- `cfg_bulk_commit`
+- `cfg_branch_list`
+- `cfg_branch_create`
+- `cfg_branch_delete`
+- `cfg_branch_diff`
+- `cfg_branch_log`
+- `cfg_pr_create`
+- `cfg_pr_list`
+- `cfg_pr_show`
+- `cfg_pr_close`
+- `cfg_pr_merge`
+- `cfg_log`
+- `cfg_show`
+- `cfg_adopt`
+- `cfg_restore`
+- `cfg_tag`
+- `cfg_fsck`
+- `cfg_whoami`
+- `cfg_init`
+- `cfg_identity_hash`
+
+A portable skill lives at `skills/cfgit/SKILL.md`.
+`cfg_impact` accepts the same `against` list/string as the CLI `--against` flag,
+so MCP clients can request scoped narration without shelling out.
+
+If `cfg_log` or `cfg_show` returns `bad_config` with a message saying history
+exists under another env, the same database has been addressed with two
+different `.cfg.toml` env names. Re-run with the env that wrote the history, or
+standardize the config so that database always uses one env name.
+
+## Impact summaries
+
+`cfg impact` runs deterministic local analysis by default. It categorizes changed
+paths, finds static references to changed values across configured records, and
+reports a risk level.
+
+Optional LLM narration lives in the separate `cfgit-impact` plugin. It reads the
+real before/after of the change plus a map of the surrounding records, then
+explains in plain language what the change does, what it ripples into, and how to
+roll it back:
+
+```bash
+pip install -e plugins/cfg_impact
+cfg impact agent_configs:agent_planner --llm --json
+```
+
+By default the narration reasons against the whole system. To scope it to a few
+records you care about, pass `--against` (repeat it, or comma-separate). The model
+then reasons about the changed record against only those selected records; no
+unselected sibling record text leaves your machine:
+
+```bash
+cfg impact agent_configs:brief_classifier \
+  --against agent_configs:critic --against agent_configs:shot_breakdown --llm
+```
+
+In the web UI the same scoping is a click: select records in the left tree and the
+button reads `Impact (2)`, scoping the analysis to that set.
+
+Provider selection comes from `[connections].ai_provider` in `.cfg.toml`, unless
+you pass `--provider`. `--llm` is gated by `[connections].share_with_ai`; add
+the exact record id, `collection:*`, or `*` before any provider call. The plugin
+supports `claude`, `openai`, and `gemini`. API keys are read from the environment
+only (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY` or `GOOGLE_API_KEY`),
+never from the config file.
+
+The core package never imports LLM provider code or vendor SDKs. That boundary is
+tested.
+
+## Storage adapters
+
+Mongo:
+
+- requires a replica set or sharded cluster for transactional writes
+- versions documents in configured collections
+- stores history in configured history and heads collections
+
+Postgres:
+
+- uses ordinary ACID transactions
+- expects each live table to have:
+  - an id column named by `id_field`
+  - optional scalar columns used by `live_when`
+  - a `doc jsonb` column containing the full record
+
+See [docs/ADAPTERS.md](docs/ADAPTERS.md).
+
+## Safety model
+
+cfgit is non-custodial. It does not stop other writers from changing the
+database. It detects and reconciles those changes.
+
+Important safety properties:
+
+- mutating operations use adapter-level compare-and-swap checks
+- commits refuse to clobber live drift
+- system restore supports dry runs
+- per-environment identity can stay open or require verified token/DB-principal identity
+- local permissions can restrict high-blast-radius actions
+- secret fields can be stripped from stored history
+- core imports no DB drivers and no LLM providers
+
+Start on a local or staging database. Do not point a new config at production
+until you have run `cfg status`, `cfg import`, `cfg diff`, and restore dry runs
+against a safe environment.
+
+## Documentation
+
+- [docs/USAGE.md](docs/USAGE.md): command flows and examples
+- [docs/CONFIGURATION.md](docs/CONFIGURATION.md): `.cfg.toml` reference
+- [docs/IDENTITY_AND_ATTRIBUTION.md](docs/IDENTITY_AND_ATTRIBUTION.md): identity modes and attribution limits
+- [docs/ADAPTERS.md](docs/ADAPTERS.md): Mongo and Postgres adapter details
+- [docs/AGENTS.md](docs/AGENTS.md): MCP, skill, and impact plugin usage
+- [docs/SPEC_CORE.md](docs/SPEC_CORE.md): project framing and v1 scope
+- [docs/SPEC.md](docs/SPEC.md): deeper engine reference
+- [docs/README.md](docs/README.md): full documentation index, including archived project notes and historical specs
+- [docs/project-notes/findings.md](docs/project-notes/findings.md): implementation findings from the origin build
+- [docs/project-notes/handoff.md](docs/project-notes/handoff.md): archived handoff notes
+- [docs/archive/spec-v0.1.md](docs/archive/spec-v0.1.md): original historical spec
+
+## Development
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+pip install -e '.[mongo,postgres,mcp,dev]'
+pip install -e plugins/cfg_impact
+ruff check src tests plugins/cfg_impact/cfg_impact
+pytest tests/ -q
+git diff --check
+```
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE), [NOTICE](NOTICE), and [CREDITS.md](CREDITS.md).