From b50c7567ea6a798b747b437d26b92bc9e4a4c2fe Mon Sep 17 00:00:00 2001 From: Matteo Rosati Date: Wed, 22 Apr 2026 22:23:00 +0200 Subject: [PATCH] remove old plans --- plans/01-_done_-move-top-level-modules.md | 37 ------------------- plans/02-_done_-typed-command-inputs.md | 35 ------------------ ...split-cli-service-repository-formatting.md | 31 ---------------- ...-centralize-chroma-client-configuration.md | 30 --------------- .../06-_done_-add-ruff-mypy-configuration.md | 30 --------------- plans/07-_done_-modernize-type-hints.md | 29 --------------- plans/08-avoid-catching-baseexception.md | 29 --------------- plans/09-domain-specific-cli-exceptions.md | 29 --------------- plans/10-configurable-ingestion.md | 30 --------------- plans/11-improve-file-handling.md | 30 --------------- plans/12-review-dependencies.md | 31 ---------------- plans/13-robust-query-result-formatting.md | 30 --------------- plans/14-clarify-delete-filter-semantics.md | 30 --------------- plans/15-command-registration-registry.md | 29 --------------- plans/16-add-verbose-logging.md | 30 --------------- plans/17-exit-code-conventions.md | 32 ---------------- plans/18-architecture-documentation.md | 30 --------------- 17 files changed, 522 deletions(-) delete mode 100644 plans/01-_done_-move-top-level-modules.md delete mode 100644 plans/02-_done_-typed-command-inputs.md delete mode 100644 plans/03-split-cli-service-repository-formatting.md delete mode 100644 plans/04-centralize-chroma-client-configuration.md delete mode 100644 plans/06-_done_-add-ruff-mypy-configuration.md delete mode 100644 plans/07-_done_-modernize-type-hints.md delete mode 100644 plans/08-avoid-catching-baseexception.md delete mode 100644 plans/09-domain-specific-cli-exceptions.md delete mode 100644 plans/10-configurable-ingestion.md delete mode 100644 plans/11-improve-file-handling.md delete mode 100644 plans/12-review-dependencies.md delete mode 100644 plans/13-robust-query-result-formatting.md delete mode 100644 plans/14-clarify-delete-filter-semantics.md delete mode 100644 plans/15-command-registration-registry.md delete mode 100644 plans/16-add-verbose-logging.md delete mode 100644 plans/17-exit-code-conventions.md delete mode 100644 plans/18-architecture-documentation.md diff --git a/plans/01-_done_-move-top-level-modules.md b/plans/01-_done_-move-top-level-modules.md deleted file mode 100644 index d952959..0000000 --- a/plans/01-_done_-move-top-level-modules.md +++ /dev/null @@ -1,37 +0,0 @@ -# 1. Move Top-Level Modules Into a Real Package [DONE] - -## Summary - -Move the current flat module layout into a proper `chromy/` package so imports, packaging, and future subpackages are easier to manage. - -## Implementation Steps - -- Create a `chromy/` package with `__init__.py`. -- Move `main.py`, `cli_app.py`, `cli_parser.py`, `chroma_functions.py`, `chunk_functions.py`, `embed.py`, and `utilities.py` into `chromy/`. -- Move `handlers/` into `chromy/handlers/`. -- Update imports to absolute package imports such as `from chromy.cli_app import execute_command` and `from chromy.handlers.add_data import handle_add_data`. -- Update `[project.scripts]` in `pyproject.toml` from `main:main` to `chromy.main:main`. -- Update setuptools configuration to package `chromy` and `chromy.handlers` instead of using top-level `py-modules`. -- Update README development commands from `uv run python main.py --help` to `uv run python -m chromy.main --help`. - -## Public Interface Changes - -- The installed CLI command remains `chromy`. -- Programmatic imports move from top-level modules to `chromy.*`. -- Running from source should use `python -m chromy.main`. - -## Test Plan - -- Run `uv run python -m chromy.main --help`. -- Run `uv run python -m chromy.main list-collections`. -- Build the package with `uv build`. -- Install locally in editable mode and confirm `chromy --help` resolves the packaged entrypoint. -- Test all commands to verify they still work: - - [creating, listing, deleting] collections - - [adding, deleting] documents to a collection (use [romeo_and_juliet.txt](romeo_and_juliet.txt)) - - querying - -## Assumptions - -- Backward-compatible top-level imports are not required. -- The package refactor should preserve behavior before deeper service or architecture changes are made. diff --git a/plans/02-_done_-typed-command-inputs.md b/plans/02-_done_-typed-command-inputs.md deleted file mode 100644 index 703bd89..0000000 --- a/plans/02-_done_-typed-command-inputs.md +++ /dev/null @@ -1,35 +0,0 @@ -# 2. Replace `argparse.Namespace` Plumbing With Typed Command Inputs [DONE] - -## Summary - -Stop passing mutable `argparse.Namespace` objects into handlers. Convert parsed CLI arguments into typed command dataclasses before dispatch. - -## Implementation Steps - -- Add frozen dataclasses for command inputs, such as list collections, create collection, delete collection, count, add data, query, and delete records. -- Keep `argparse` isolated in the CLI adapter layer. -- Convert `Namespace` into the correct command dataclass immediately before dispatch. -- Change handler signatures from `Callable[[Namespace], int]` to typed command-specific callables. -- Remove mutations such as `args.error_message = ...` in `cli_app.py` and `handlers/delete_collection.py`. -- Return or raise explicit structured results/errors rather than writing temporary state back into the parsed args object. - -## Public Interface Changes - -- CLI command syntax stays the same. -- Internal handler APIs change to typed dataclass inputs. -- Error message builders should receive typed command inputs or exceptions instead of raw `Namespace`. - -## Test Plan - -- Add parser-to-command conversion tests for every command and alias. -- Add handler unit tests that construct command dataclasses directly. -- Verify invalid delete filters still produce the same user-facing error. -- Test all commands to verify they still work: - - [creating, listing, deleting] collections - - [adding, deleting] documents to a collection (use [romeo_and_juliet.txt](romeo_and_juliet.txt)) - - querying - -## Assumptions - -- Command dataclasses should live near CLI application code until a broader package refactor introduces clearer subpackages. -- The first pass should preserve the existing command names, arguments, aliases, and output. diff --git a/plans/03-split-cli-service-repository-formatting.md b/plans/03-split-cli-service-repository-formatting.md deleted file mode 100644 index 9abf57a..0000000 --- a/plans/03-split-cli-service-repository-formatting.md +++ /dev/null @@ -1,31 +0,0 @@ -# 3. Split CLI, Service, Repository, and Formatting Responsibilities - -## Summary - -Separate command handling, business workflows, Chroma persistence, and output formatting so each layer has a single responsibility. - -## Implementation Steps - -- Keep handlers thin: receive typed command input, call a service, and print formatted output. -- Move ingestion orchestration from `utilities.ingest_file` into an `IngestionService`. -- Move query orchestration from `utilities.run_query` into a `QueryService`. -- Move Chroma collection operations from `chroma_functions.py` into a `ChromaRepository` or `ChromaStore`. -- Move output-only functions such as `format_query_result` and `print_lines` into a formatting module. -- Keep Chroma-specific result parsing out of CLI handlers. - -## Public Interface Changes - -- CLI behavior remains unchanged. -- Internal APIs become service and repository methods instead of free functions. -- Formatting functions should accept internal domain objects rather than raw Chroma response dictionaries where possible. - -## Test Plan - -- Unit test services with mocked repository, chunker, and embedder dependencies. -- Unit test formatter output without requiring Chroma. -- Run a small manual CLI smoke test for create, add, query, count, list, and delete. - -## Assumptions - -- This should be done after typed command inputs and package layout changes, or coordinated carefully with them. -- No JSON output mode or web API is added in this refactor; the goal is to make those future changes easier. diff --git a/plans/04-centralize-chroma-client-configuration.md b/plans/04-centralize-chroma-client-configuration.md deleted file mode 100644 index 1f108e0..0000000 --- a/plans/04-centralize-chroma-client-configuration.md +++ /dev/null @@ -1,30 +0,0 @@ -# 4. Centralize Chroma Client Configuration - -## Summary - -Create Chroma client configuration once per command and inject it into repository or service objects instead of repeatedly calling `chromadb.PersistentClient()`. - -## Implementation Steps - -- Add a small configuration object for Chroma settings, including persistence path. -- Load the persistence path from a CLI option, environment variable, or default Chroma behavior. -- Create a Chroma client factory that returns one client per command execution. -- Inject the client into the Chroma repository instead of constructing it inside each function. -- Remove repeated `chromadb.PersistentClient()` calls from collection operations. -- Ensure tests can pass an in-memory or temporary Chroma client. - -## Public Interface Changes - -- Add a documented way to configure the Chroma persistence path. -- Existing commands should continue to work with the current implicit default when no path is provided. - -## Test Plan - -- Unit test repository operations with an injected test client. -- Verify two commands using the same configured persistence directory can see the same collections. -- Verify default behavior still works when no path is configured. - -## Assumptions - -- The initial implementation should preserve Chroma's default persistence behavior unless a path is explicitly configured. -- Configuration should be introduced before larger repository and service tests depend on isolated storage. diff --git a/plans/06-_done_-add-ruff-mypy-configuration.md b/plans/06-_done_-add-ruff-mypy-configuration.md deleted file mode 100644 index 5a76ba0..0000000 --- a/plans/06-_done_-add-ruff-mypy-configuration.md +++ /dev/null @@ -1,30 +0,0 @@ -# 6. Add Ruff and Mypy Configuration [DONE] - -## Summary - -Add linting, formatting, and static type checking configuration to `pyproject.toml`. Do not add pytest configuration for this improvement. - -## Implementation Steps - -- Add `ruff` and `mypy` to the development dependency group. -- Configure Ruff formatting and lint rules in `pyproject.toml`. -- Configure mypy in strict or near-strict mode suitable for the current Chroma and third-party boundaries. -- Add README development commands for `uv run ruff check .`, `uv run ruff format .`, and `uv run mypy .`. -- Fix only minimal configuration blockers in this plan; broad type modernization belongs to the type-hints plan. - -## Public Interface Changes - -- No runtime CLI behavior changes. -- Development workflow gains standard lint, format, and type-check commands. - -## Test Plan - -- Run `uv run ruff check .`. -- Run `uv run ruff format --check .`. -- Run `uv run mypy .`. -- Confirm no pytest configuration is added as part of this plan. - -## Assumptions - -- Pytest is intentionally out of scope for this improvement. -- Strict mypy may need targeted ignores for third-party packages that do not expose complete typing. diff --git a/plans/07-_done_-modernize-type-hints.md b/plans/07-_done_-modernize-type-hints.md deleted file mode 100644 index 876a931..0000000 --- a/plans/07-_done_-modernize-type-hints.md +++ /dev/null @@ -1,29 +0,0 @@ -# 7. Modernize Type Hints and Add Missing Future Imports [DONE] - -## Summary - -Make type annotations consistent across the codebase by using modern Python 3.12 typing syntax and adding future annotations imports where useful. - -## Implementation Steps - -- Add `from __future__ import annotations` consistently to Python modules that do not already have it. -- Replace `typing.List` with built-in generic syntax such as `list[str]` and `list[EmbeddingRecord]`. -- Use `collections.abc` input interfaces such as `Sequence[str]` where mutation is not required. -- Introduce type aliases or dataclasses for internal Chroma result shapes only where they reduce ambiguity. -- Keep runtime behavior unchanged. - -## Public Interface Changes - -- No CLI behavior changes. -- Public Python annotations become more precise and consistent. - -## Test Plan - -- Run `uv run ruff check .`. -- Run `uv run mypy .` after mypy configuration exists. -- Manually smoke test CLI commands that touched type boundaries. - -## Assumptions - -- The project remains Python 3.12+, so built-in generic syntax is acceptable everywhere. -- Larger domain model changes should be handled in the service/repository and query-formatting plans. diff --git a/plans/08-avoid-catching-baseexception.md b/plans/08-avoid-catching-baseexception.md deleted file mode 100644 index fc46fba..0000000 --- a/plans/08-avoid-catching-baseexception.md +++ /dev/null @@ -1,29 +0,0 @@ -# 8. Avoid Catching `BaseException` in CLI Dispatch - -## Summary - -Change CLI dispatch error handling so process-control exceptions such as `KeyboardInterrupt` and `SystemExit` are not swallowed. - -## Implementation Steps - -- Change `execute_command` to catch `Exception` instead of `BaseException`. -- Keep mapped, expected errors handled through the existing command error mapping or its replacement. -- Print handled user-facing errors to `stderr` instead of `stdout`. -- Allow unmapped exceptions, `KeyboardInterrupt`, and `SystemExit` to propagate normally. -- Consider adding debug logging for unexpected exceptions after the logging plan exists. - -## Public Interface Changes - -- Expected command errors still return a non-zero exit code. -- Handled error messages move from stdout to stderr. -- Interrupt and process-exit behavior becomes conventional. - -## Test Plan - -- Test that a mapped exception returns `1` and writes to stderr. -- Test that `KeyboardInterrupt` is not caught by `execute_command`. -- Test that unmapped exceptions still propagate. - -## Assumptions - -- Returning `1` for handled user errors remains acceptable until the exit-code conventions plan is implemented. diff --git a/plans/09-domain-specific-cli-exceptions.md b/plans/09-domain-specific-cli-exceptions.md deleted file mode 100644 index 6a5d364..0000000 --- a/plans/09-domain-specific-cli-exceptions.md +++ /dev/null @@ -1,29 +0,0 @@ -# 9. Use Domain-Specific Exceptions Instead of Chroma Exceptions in CLI Mapping - -## Summary - -Hide Chroma-specific exceptions behind application-level exceptions so the CLI does not depend on Chroma's exception model. - -## Implementation Steps - -- Define app-level exceptions such as `CollectionNotFoundError`, `CollectionAlreadyExistsError`, and `StorageOperationError`. -- Convert Chroma exceptions inside the repository layer. -- Update CLI command error mappings to handle app-level exceptions only. -- Preserve existing user-facing messages for missing and duplicate collections. -- Avoid importing `chromadb.errors` in CLI modules after the repository layer owns that boundary. - -## Public Interface Changes - -- CLI behavior and messages should remain the same. -- Internal error contracts change from Chroma exceptions to app-level exceptions. - -## Test Plan - -- Unit test repository exception translation. -- Unit test CLI mappings for app-level exceptions. -- Smoke test missing collection, duplicate collection, and successful operations. - -## Assumptions - -- Chroma remains the only storage backend for now. -- The exception layer is still useful because it prevents storage details from leaking upward. diff --git a/plans/10-configurable-ingestion.md b/plans/10-configurable-ingestion.md deleted file mode 100644 index e9d2291..0000000 --- a/plans/10-configurable-ingestion.md +++ /dev/null @@ -1,30 +0,0 @@ -# 10. Make Ingestion More Configurable - -## Summary - -Move chunking and embedding choices into configuration and expose chunk size as an `add-data` CLI option. - -## Implementation Steps - -- Add ingestion configuration for chunk size, tokenizer/model name, and embedding function provider. -- Change chunking code to receive chunk size and tokenizer/model name instead of hard-coding `800` and `"gpt-4"`. -- Reuse the embedding function through dependency injection instead of constructing it for every embed call. -- Add `--chunk-size` to `add-data`, defaulting to the current value of `800`. -- Keep the default tokenizer/model behavior equivalent to the current `"gpt-4"` setting. - -## Public Interface Changes - -- `add-data` gains `--chunk-size`. -- Default ingestion behavior remains unchanged when no option is provided. - -## Test Plan - -- Test chunking with default and custom chunk sizes. -- Test `add-data --chunk-size` parser behavior. -- Test ingestion service with an injected fake embedder. -- Smoke test adding a file with and without `--chunk-size`. - -## Assumptions - -- Only chunk size is exposed in the CLI initially. -- Tokenizer/model and embedding provider configuration can remain internal or environment-backed until there is a concrete user-facing need. diff --git a/plans/11-improve-file-handling.md b/plans/11-improve-file-handling.md deleted file mode 100644 index 9429b54..0000000 --- a/plans/11-improve-file-handling.md +++ /dev/null @@ -1,30 +0,0 @@ -# 11. Improve File Handling - -## Summary - -Make file ingestion boundaries clearer by using `Path`, explicit UTF-8 decoding, and validation before reading. - -## Implementation Steps - -- Change internal file ingestion APIs to accept `Path` instead of raw `str`. -- Convert CLI string paths to `Path` in the command adapter or handler. -- Validate that the path exists and is a regular file before reading. -- Read text with `encoding="utf-8"`. -- Raise a clear app-level file error for missing paths, directories, and decoding failures. -- Leave PDF and future file loaders out of scope for now. - -## Public Interface Changes - -- CLI argument remains a file path string. -- Error messages for missing or invalid files become clearer. - -## Test Plan - -- Test successful text-file loading. -- Test missing file, directory path, and invalid UTF-8 handling. -- Smoke test `add-data` with a valid UTF-8 file. - -## Assumptions - -- Only plain text ingestion is supported in this plan. -- Existing metadata can continue storing the original path string as `file_name` unless a later plan changes metadata shape. diff --git a/plans/12-review-dependencies.md b/plans/12-review-dependencies.md deleted file mode 100644 index 5d9d906..0000000 --- a/plans/12-review-dependencies.md +++ /dev/null @@ -1,31 +0,0 @@ -# 12. Review Dependencies and Remove Unused Ones - -## Summary - -Audit runtime dependencies and move unused or optional packages out of the base install where appropriate. - -## Implementation Steps - -- Compare imports in source code against dependencies declared in `pyproject.toml`. -- Keep packages that are directly imported by current runtime code. -- Move packages used only for optional or future features behind extras, such as `pdf` or `openai`. -- Remove dependencies that are neither imported nor needed transitively by active code. -- Update `uv.lock` after dependency changes. -- Update README installation notes if extras are introduced. - -## Public Interface Changes - -- Base installation may become smaller. -- Optional feature dependencies should be installed through extras if introduced. - -## Test Plan - -- Run `uv sync` after dependency edits. -- Run `uv run python -m chromy.main --help`. -- Smoke test commands that use Chroma, semchunk, dotenv loading, and embedding. -- Build the package with `uv build`. - -## Assumptions - -- Dependency removal should be conservative and based on actual import usage. -- No new optional features are implemented as part of this cleanup. diff --git a/plans/13-robust-query-result-formatting.md b/plans/13-robust-query-result-formatting.md deleted file mode 100644 index ef5f4aa..0000000 --- a/plans/13-robust-query-result-formatting.md +++ /dev/null @@ -1,30 +0,0 @@ -# 13. Make Query Result Formatting More Robust - -## Summary - -Convert raw Chroma query results into typed internal matches before formatting them for terminal output. - -## Implementation Steps - -- Add a `QueryMatch` dataclass with fields for id, document, distance, and metadata. -- Add a parser that converts Chroma `QueryResult` data into `list[QueryMatch]`. -- Handle empty results, missing documents, missing metadata, missing distances, and unexpected metadata shapes defensively. -- Change terminal formatting to accept `list[QueryMatch]`. -- Keep current text output as stable as practical. - -## Public Interface Changes - -- CLI output should remain effectively the same for normal query results. -- Internal formatter APIs change from raw Chroma result dictionaries to typed match objects. - -## Test Plan - -- Test empty query results. -- Test populated results with ids, documents, distances, and metadata. -- Test missing documents, missing metadata, multiple query result groups, and non-mapping metadata values. -- Smoke test `query` against a real collection. - -## Assumptions - -- The first implementation can format the first query group only, matching current behavior. -- Support for alternate output formats is not added in this plan. diff --git a/plans/14-clarify-delete-filter-semantics.md b/plans/14-clarify-delete-filter-semantics.md deleted file mode 100644 index 7a372e7..0000000 --- a/plans/14-clarify-delete-filter-semantics.md +++ /dev/null @@ -1,30 +0,0 @@ -# 14. Clarify Delete Filter Semantics - -## Summary - -Make it clear that record deletion supports a simple metadata equality filter in `key=value` form. - -## Implementation Steps - -- Rename internal parser variables from `condition` to `key` where equality-only semantics are intended. -- Update CLI help for `--where` to say `Metadata equality filter in the format =`. -- Update error messages to use `=`. -- Update README command documentation to include the `delete` command and its filter syntax. -- Reserve richer Chroma filters, such as JSON filters, for a later feature. - -## Public Interface Changes - -- CLI option remains `--where`. -- Help text and error messages become more precise. -- No richer filter syntax is added yet. - -## Test Plan - -- Test valid `key=value` parsing with whitespace trimming. -- Test missing separator, empty key, and empty value errors. -- Verify `chromy delete --help` documents equality semantics. - -## Assumptions - -- Keeping the option name `--where` is acceptable for backward compatibility. -- Renaming to `--key` is not worth the CLI break for the current feature set. diff --git a/plans/15-command-registration-registry.md b/plans/15-command-registration-registry.md deleted file mode 100644 index 96f5a0a..0000000 --- a/plans/15-command-registration-registry.md +++ /dev/null @@ -1,29 +0,0 @@ -# 15. Improve Command Registration So Parser and Dispatcher Cannot Drift - -## Summary - -Unify command parser metadata, handlers, aliases, and error mappings into one registry or add a startup check that prevents parser and dispatcher drift. - -## Implementation Steps - -- Create one command registry that includes command name, aliases, help text, arguments, handler, and expected error mappings. -- Build argparse subcommands from the registry. -- Dispatch commands through the same registry. -- Remove duplicated command declarations from separate parser and app structures. -- Add a small validation check that command names are unique and aliases do not collide. - -## Public Interface Changes - -- CLI command names, aliases, arguments, and help text should remain the same. -- Internal command registration becomes centralized. - -## Test Plan - -- Test that every registry command appears in parser help. -- Test every alias dispatches to the canonical command. -- Test duplicate command or alias validation fails fast. -- Smoke test all existing commands through parser and dispatcher. - -## Assumptions - -- A unified registry is preferred over only adding a drift-detection test because the current repo already has structured command metadata. diff --git a/plans/16-add-verbose-logging.md b/plans/16-add-verbose-logging.md deleted file mode 100644 index 1d4bb2d..0000000 --- a/plans/16-add-verbose-logging.md +++ /dev/null @@ -1,30 +0,0 @@ -# 16. Add Logging for Debuggability - -## Summary - -Add optional diagnostic logging for ingestion, query, and Chroma operations while keeping normal CLI output clean. - -## Implementation Steps - -- Configure Python's `logging` module in the CLI entrypoint. -- Add a global `--verbose` flag to enable debug-level logs. -- Log file loading, chunk counts, embedding calls, Chroma writes, collection operations, and query timing. -- Send logs to stderr so stdout remains reserved for command output. -- Avoid logging document contents or full embeddings. - -## Public Interface Changes - -- Add global CLI flag `--verbose`. -- Normal output remains unchanged when verbose mode is not enabled. - -## Test Plan - -- Test parser behavior for `--verbose`. -- Test that debug logs are suppressed by default. -- Test that verbose mode emits representative diagnostic logs to stderr. -- Smoke test `add-data` and `query` with verbose mode enabled. - -## Assumptions - -- A single global verbosity level is enough for now. -- Structured logging means consistent logger names and message fields, not a JSON logging format. diff --git a/plans/17-exit-code-conventions.md b/plans/17-exit-code-conventions.md deleted file mode 100644 index 891fba3..0000000 --- a/plans/17-exit-code-conventions.md +++ /dev/null @@ -1,32 +0,0 @@ -# 17. Add Exit Code Conventions - -## Summary - -Document and implement consistent exit codes so scripts can distinguish success from expected user errors. - -## Implementation Steps - -- Define named constants or an enum for exit codes. -- Use `0` for success. -- Use `1` for expected user-facing errors initially. -- Optionally reserve distinct documented codes for validation errors, missing collections, and file errors if the CLI needs them. -- Update error handling to return constants instead of literal integers. -- Document exit code behavior in README. - -## Public Interface Changes - -- Existing successful commands still exit `0`. -- Existing handled errors may continue to exit `1` unless distinct codes are explicitly adopted. -- README documents the convention. - -## Test Plan - -- Test success returns `0`. -- Test expected user errors return the documented code. -- Test unexpected exceptions still propagate to the runtime. -- Manually verify shell exit status for representative commands. - -## Assumptions - -- Start with `0` and `1` unless there is a clear automation need for more granular codes. -- This plan should follow the exception cleanup plan so errors are categorized at the app level. diff --git a/plans/18-architecture-documentation.md b/plans/18-architecture-documentation.md deleted file mode 100644 index 3143f05..0000000 --- a/plans/18-architecture-documentation.md +++ /dev/null @@ -1,30 +0,0 @@ -# 18. Add Repository-Level Documentation for Architecture - -## Summary - -Document the intended internal architecture so future changes follow the same parser, handler, service, repository, and formatter boundaries. - -## Implementation Steps - -- Add a "Development Architecture" section to README or create `docs/architecture.md`. -- Describe the request flow: CLI parser -> command input -> handler -> service -> Chroma repository -> formatter. -- Explain where to add a new command. -- Explain where to add a new document loader. -- Explain where to add a new embedding provider. -- Include the default Chroma persistence behavior and how configuration is injected after that refactor exists. - -## Public Interface Changes - -- No runtime behavior changes. -- Developer-facing documentation is added or expanded. - -## Test Plan - -- Verify documentation matches the actual package/module layout after refactors. -- Run README examples to ensure commands are still accurate. -- Check links and command snippets manually. - -## Assumptions - -- Documentation should be updated after or alongside the architecture refactor so it describes the intended final shape. -- A README section is enough unless the architecture content grows too large.