conveoconfi 0.1.0__tar.gz

conveoconfi-0.1.0/.agents/.gitignore

@@ -0,0 +1 @@
+*

conveoconfi-0.1.0/.agents/GUIDELINES.md

@@ -0,0 +1,4 @@
+## Commit Rules
+
+- When you make a git commit, always use `Semantic Commit Messages` described in the document @.agents/code-standards/conventional-commits-messages.md
+- When you create or update a "markdown" `.md` file in a "dot folder" `.folder` related to documentation, explanation, task/issue reporting or logging the work, use the skill `latest-commit` to track when exactly the file was created or updated.

conveoconfi-0.1.0/.agents/PRD.md

@@ -0,0 +1,163 @@
+## Problem Statement
+
+The projects `cheapchocolate`, `ohmyscrapper`, and `aphantasist` each carry their own copy of a `core.config_files` module. These copies implement the same convention-over-configuration behavior: YAML files are created from bundled defaults when missing, existing YAML files are completed from defaults when new parameters are introduced, and callers can read nested parameters through a small function-based API.
+
+Keeping this behavior duplicated across projects makes maintenance risky. A bug fix or behavior improvement has to be copied by hand into every project, and the copies have already diverged: `cheapchocolate` completes missing nested dictionary values, while `ohmyscrapper` and `aphantasist` only complete missing top-level keys. The developer wants a reusable dependency library named `conveoconfi` that can replace each local `config_files.py` with minimal migration work: add the dependency, change imports, and delete the duplicated module.
+
+## Solution
+
+Create `conveoconfi` as a Python dependency that provides the same public usage surface as the existing `config_files.py` modules while allowing each consuming project to provide its own YAML default templates.
+
+From the consuming developer's perspective, migration should be simple:
+
+1. Add `conveoconfi` as a Python dependency.
+2. Replace imports from the project-local `core.config_files` module with imports from `conveoconfi`.
+3. Keep existing calls to `create_and_read_config_file`, `complete_config_file`, `overwrite_config_file`, `append_config_file`, `get_param`, `config_file_exists`, and `config_file_path` working.
+4. Delete the old project-local `config_files.py`.
+5. Keep project-specific default YAML files in the consuming project, or explicitly point `conveoconfi` to their default-template directory.
+
+The library should preserve the current convention-over-configuration model:
+
+- The configured application directory is created when needed.
+- Missing config files are created from default YAML templates.
+- Existing config files are read from disk.
+- Missing parameters are completed from default templates and persisted back to the current config file.
+- Empty or unreadable-as-empty YAML config files are replaced with default content.
+- Parameter reads use `config.yaml` as the root config file by default, matching the existing behavior.
+
+## User Stories
+
+1. As a maintainer of multiple Python projects, I want one shared configuration library, so that I do not maintain duplicate `config_files.py` modules.
+2. As a maintainer of `cheapchocolate`, I want to replace `cheapchocolate.core.config_files` with `conveoconfi`, so that future config behavior fixes come from one dependency.
+3. As a maintainer of `ohmyscrapper`, I want to replace `ohmyscrapper.core.config_files` with `conveoconfi`, so that the scraper keeps its existing YAML configuration workflow.
+4. As a maintainer of `aphantasist`, I want to replace `aphantasist.core.config_files` with `conveoconfi`, so that the project no longer carries duplicated config utility code.
+5. As a consuming developer, I want the public functions to keep their current names, so that migration is mostly an import change.
+6. As a consuming developer, I want the current function arguments to remain valid, so that existing callers do not require behavioral rewrites.
+7. As a consuming developer, I want `create_and_read_config_file` to create a missing app config directory, so that first-run setup remains automatic.
+8. As a consuming developer, I want `create_and_read_config_file` to create a missing config file from a YAML template, so that users get working defaults without manual setup.
+9. As a consuming developer, I want `create_and_read_config_file` to return parsed YAML data, so that existing code can continue reading dict-like config values.
+10. As a consuming developer, I want `create_and_read_config_file` to honor `force_default=True`, so that callers can deliberately reset a config file to defaults.
+11. As a consuming developer, I want `create_and_read_config_file` to honor `complete_file=False`, so that callers can read a file without mutating it.
+12. As a consuming developer, I want existing user-provided values to be preserved during completion, so that updates do not overwrite local choices.
+13. As a consuming developer, I want missing top-level keys to be copied from the default template, so that new release defaults appear in old config files.
+14. As a consuming developer, I want missing nested dictionary keys to be copied from the default template, so that newly introduced nested settings work for existing users.
+15. As a maintainer of `cheapchocolate`, I want nested completion to preserve existing nested values, so that existing behavior around `mails.remote_read_state` is retained.
+16. As a maintainer of `ohmyscrapper`, I want nested config sections such as `sniffing`, `queue`, `db`, and `ai` to keep existing user values, so that upgrades do not break scraping behavior.
+17. As a maintainer of `aphantasist`, I want simple config files with only top-level defaults to keep working, so that the library does not require unnecessary project-specific setup.
+18. As a consuming developer, I want empty YAML files to be replaced with defaults, so that an accidental blank config file recovers automatically.
+19. As a consuming developer, I want `overwrite_config_file` to write YAML data to the target config file, so that wrappers can keep their current behavior.
+20. As a consuming developer, I want `append_config_file` to append YAML data and then normalize the file, so that existing append workflows keep working.
+21. As a consuming developer, I want `get_param` to read a child parameter from a parent section in `config.yaml`, so that existing `get_dir`, `get_file`, and similar wrappers keep working.
+22. As a consuming developer, I want `get_param` to raise the same style of exception when a parameter is missing, so that existing error handling remains predictable.
+23. As a consuming developer, I want `config_file_exists` to report whether a config file exists in the app directory, so that seed and setup workflows can branch correctly.
+24. As a consuming developer, I want `config_file_path` to return the filesystem path and ensure the app directory exists, so that wrappers can reuse that convention.
+25. As a consuming developer, I want default templates to be loaded from a project-controlled default-files directory, so that each project can keep its own `config.yaml`, `mail_folders.yaml`, `url_types.yaml`, and `url_sniffing.yaml`.
+26. As a consuming developer, I want to configure the default-template location explicitly, so that templates no longer have to live next to the old duplicated module.
+27. As a consuming developer, I want the library to use safe YAML loading, so that config parsing avoids arbitrary object construction.
+28. As a consuming developer, I want YAML output to stay simple and compatible with existing files, so that generated configs remain easy to inspect and edit.
+29. As a consuming developer, I want Unicode values to be preserved when appending data, so that non-ASCII user-provided config values remain valid.
+30. As a library maintainer, I want the completion algorithm isolated behind a small interface, so that it can be tested without filesystem side effects.
+31. As a library maintainer, I want file IO isolated behind a small interface, so that filesystem behavior can be tested with temporary directories.
+32. As a library maintainer, I want default-template lookup isolated behind a small interface, so that future package-resource support does not disturb callers.
+33. As a library maintainer, I want compatibility tests based on the three source projects, so that regressions are caught before the dependency is adopted.
+34. As a release maintainer, I want package metadata to declare the YAML dependency, so that consumers install everything needed automatically.
+35. As a release maintainer, I want a clear README migration guide, so that project maintainers know exactly which imports to change.
+36. As a release maintainer, I want the first release to be intentionally small, so that adoption risk stays focused on replacing the duplicated module.
+37. As an application user, I want the program to keep starting with sensible defaults, so that I do not need to learn new configuration steps after the migration.
+38. As an application user, I want my existing config files to keep their custom values, so that upgrading a project does not reset my local environment.
+39. As an application user, I want newly released options to appear in my config file automatically, so that I can discover and edit them after an upgrade.
+40. As a consuming developer, I want failures for missing default templates to be explicit, so that packaging mistakes are easy to diagnose.
+
+## Implementation Decisions
+
+- Build `conveoconfi` as a Python library package rather than an application script.
+- Preserve the function-based API from the existing modules as the initial public compatibility surface.
+- Include these public functions in the compatibility surface: `create_and_read_config_file`, `complete_config_file`, `overwrite_config_file`, `append_config_file`, `get_param`, `config_file_exists`, and `config_file_path`.
+- Keep `file_name`, `default_app_dir`, `force_default=False`, and `complete_file=True` semantics for `create_and_read_config_file`.
+- Keep `get_param(parent_param, param, default_app_dir)` reading from `config.yaml`, matching the existing modules.
+- Keep app-directory creation as part of path resolution, matching the existing `config_file_path` side effect.
+- Add an explicit way to configure where default YAML templates are loaded from, because a reusable dependency cannot assume the templates live in its own package directory.
+- Prefer an explicit default-template directory argument or small configuration object over hidden global state for new code, while keeping the legacy call pattern available for migration.
+- Treat default-template lookup as a deep module: it should hide package-resource and filesystem lookup details behind a stable interface.
+- Treat config completion as a deep module: it should merge missing defaults into existing parsed data without knowing anything about disk paths.
+- Treat YAML file persistence as a deep module: it should centralize safe loading, safe dumping, append-normalize behavior, and recovery from empty YAML files.
+- Use recursive dictionary completion as the target default behavior because it is the stricter convention-over-configuration behavior and is already required by `cheapchocolate`.
+- Preserve existing configured values during recursive completion and only fill missing keys from the template.
+- Do not remove user-defined extra keys that are not present in the template.
+- If a default value is a dictionary but the current value is not a dictionary, preserve the current value rather than replacing it implicitly.
+- If a current value is a dictionary but the default value is not a dictionary, preserve the current value rather than replacing it implicitly.
+- Continue using PyYAML as the YAML implementation because the source projects already depend on `yaml.safe_load`, `yaml.safe_dump`, and `yaml.dump`.
+- Add PyYAML as a package dependency.
+- Keep generated YAML human-readable and compatible with existing source-project behavior.
+- Keep the initial library narrowly focused on YAML template-backed configuration files.
+- Provide documentation showing the migration from `from <project>.core import config_files` to the new dependency import.
+- Provide documentation showing how a consuming project points the library at its own default template directory.
+- Preserve compatibility with Python 3.11 and newer, matching the current project scaffold.
+- Use source-project fixtures based on `cheapchocolate`, `ohmyscrapper`, and `aphantasist` default YAML files to validate compatibility.
+- Capture upstream reference points used for this PRD:
+  - `cheapchocolate` main at `4bdd25d522788cb6463c3f0eca494de2a9244a76`, dated `2026-06-17T09:18:39+02:00`, `Bump version: 0.5.4 -> 0.6.0`.
+  - `ohmyscrapper` main at `fc6223ddaeade264fcc0e857712ff97d9de49546`, dated `2026-06-07T16:17:25+02:00`, `Bump version: 0.10.1 -> 0.10.2`.
+  - `aphantasist` main at `a4f70a890909823dd8d4462529bc20ddc4f375a5`, dated `2026-01-07T18:35:08+01:00`, `Bump version: 0.0.1 -> 0.1.0`.
+
+## Testing Decisions
+
+- Tests should assert external behavior: returned config data, created files, completed files, preserved user values, raised errors, and filesystem side effects.
+- Tests should not assert private helper call order or internal implementation details.
+- Test the completion module independently with plain dictionaries.
+- Test that top-level missing keys are added from defaults.
+- Test that nested missing keys are added from defaults.
+- Test that existing nested values are preserved.
+- Test that unknown user-defined keys are preserved.
+- Test that scalar-vs-dictionary conflicts preserve existing user values.
+- Test the YAML persistence module with temporary directories and real files.
+- Test creation of a missing config file from a default template.
+- Test recovery when an existing config file parses as `None`.
+- Test `force_default=True` overwrites an existing config file with defaults.
+- Test `complete_file=False` reads without mutating an incomplete file.
+- Test `overwrite_config_file` writes readable YAML.
+- Test `append_config_file` appends data and normalizes duplicate content through a read/write cycle.
+- Test `config_file_exists` before and after file creation.
+- Test `config_file_path` returns the expected path and creates the app directory.
+- Test `get_param` returns a known child value from `config.yaml`.
+- Test `get_param` raises the expected exception message when the child value is missing.
+- Add compatibility fixture tests using the default YAML shapes from `cheapchocolate`, `ohmyscrapper`, and `aphantasist`.
+- Use the `cheapchocolate` existing test `test_complete_config_file_preserves_existing_nested_values` as prior art for nested completion behavior.
+- Use source-project wrapper tests as migration confidence checks, but keep this library's unit tests focused on the shared config-file behavior.
+- Use temporary directories for all filesystem tests so that tests do not touch a developer's real application config.
+
+## Out of Scope
+
+- Rewriting the consuming projects' higher-level `core.config` wrapper modules.
+- Migrating `cheapchocolate`, `ohmyscrapper`, or `aphantasist` in this PRD.
+- Introducing a new configuration schema language.
+- Validating config values beyond preserving and completing YAML data.
+- Supporting non-YAML config formats.
+- Managing environment-variable overrides.
+- Providing a command-line interface.
+- Providing application-specific default YAML templates inside `conveoconfi`.
+- Removing or renaming legacy public functions during the first compatibility release.
+- Changing project-specific business rules such as mail folders, URL sniffing behavior, queue settings, or scraper policies.
+
+## Further Notes
+
+The main design risk is default-template discovery. The old modules used `os.path.dirname(os.path.realpath(__file__))` and expected templates in a sibling `default_files` directory. A dependency library cannot infer the consuming project's template directory from its own `__file__`, so the replacement needs a deliberate compatibility mechanism.
+
+The second design risk is completion depth. The user request says behavior must be exactly the same regarding usage, but the referenced projects are not behaviorally identical. The PRD chooses recursive completion as the target because it preserves all top-level behavior while also supporting the newer nested-completion behavior already present and tested in `cheapchocolate`.
+
+The current `conveoconfi` repository is an initial scaffold with no commits yet, a Python 3.11 project declaration, no dependencies, an empty README, and a simple `main.py` placeholder.
+
+## Latest Git Reference
+
+Latest commit when this document was written:
+
+Hash: none
+Date: none
+Description: this repository has no commits yet
+
+## Latest Git Reference for this file
+
+Latest commit when this document was written:
+
+Hash: none
+Date: none
+Description: this repository has no commits yet

conveoconfi-0.1.0/.agents/PROGRESS.md

@@ -0,0 +1,100 @@
+## 001 - Bootstrap Importable Library Package
+
+Status: complete
+
+- Added `src/conveoconfi` as the importable package entrypoint.
+- Exposed the legacy public function names from `conveoconfi.__all__` with clear not-yet-implemented stubs.
+- Declared PyYAML as the runtime YAML dependency and added pytest test metadata.
+- Added an import test covering the package import path and public function names.
+
+## 002 - Create Config Files From Project Templates
+
+Status: complete
+
+- Implemented `config_file_path` so resolving a config path creates the app config directory.
+- Implemented `create_and_read_config_file` for missing file creation from an explicit project template directory, safe YAML loading, human-readable YAML writing, empty-file recovery, and explicit template lookup failures.
+- Added tests covering app directory creation, missing config file creation, empty-file recovery, existing config reads, returned parsed data, and template lookup errors.
+
+## 003 - Complete Existing Config Files Recursively
+
+Status: complete
+
+- Added recursive dictionary completion that fills missing default keys while preserving existing user values and user-defined extra keys.
+- Wired existing-file reads through completion by default, with `complete_file=False` preserving the existing no-mutation read behavior.
+- Implemented `complete_config_file` for direct legacy-style completion calls.
+- Preserved current values when default and current YAML shapes conflict between dictionaries and scalars.
+- Added tests for recursive completion, preservation rules, `force_default=True`, and no-mutation reads.
+
+## 004 - Preserve Legacy File Operations
+
+Status: complete
+
+- Implemented `overwrite_config_file` to write readable YAML to the requested app config file while creating the app directory through path resolution.
+- Implemented `append_config_file` to append YAML data, reload it, and rewrite normalized YAML so duplicate appended keys collapse to a single emitted value.
+- Preserved Unicode values during append normalization through UTF-8 file IO and unicode-enabled YAML dumping.
+- Implemented `config_file_exists` using the shared config path convention.
+- Added temporary-directory filesystem tests for overwrite, append normalization, Unicode preservation, config existence, and config path side effects.
+
+## Latest Git Reference for this file
+
+Latest commit when this document was written:
+
+Hash: 762bb451ae337daefcfe7963df8c794851f86c35
+Date: 2026-06-17T10:23:51+02:00
+Description: feat: create config files from templates
+
+## 005 - Preserve Legacy Parameter Reads
+
+Status: complete
+
+- Implemented `get_param(parent_param, param, default_app_dir, ...)` to read child values from `config.yaml` through the shared create/read/complete path.
+- Kept the legacy three-argument call valid while allowing explicit `default_files_dir` or `default_template_dir` kwargs for template lookup.
+- Added missing-child error handling with a legacy-style exception message that names the requested child and parent.
+- Added tests for successful reads from newly created config files, completion before parameter reads, and missing child parameter errors.
+- Verified with `uv run pytest -q` passing 17 tests.
+
+## Latest Git Reference for this file
+
+Latest commit when this document was written:
+
+Hash: ee84a8cd5952f83fa63a1faa47d919db7a4fa00e
+Date: 2026-06-17T10:37:16+02:00
+Description: feat: preserve legacy parameter reads
+
+## 006 - Add Source Project Compatibility Fixtures
+
+Status: complete
+
+- Added compatibility fixture tests for representative `cheapchocolate`, `ohmyscrapper`, and `aphantasist` YAML config shapes.
+- Verified `cheapchocolate`-style nested mail state completion preserves existing nested values while adding missing nested defaults.
+- Verified `ohmyscrapper`-style sections including `db`, `default_dirs`, `default_files`, `ai`, `sniffing`, and `queue` can be created and recursively completed through the public API.
+- Verified an `aphantasist`-style simple config can be created from defaults and read through `get_param`.
+- Documented the upstream reference commits used for fixture behavior in the test module.
+- Verified with `uv run pytest -q` passing 20 tests.
+
+## Latest Git Reference for this file
+
+Latest commit when this document was written:
+
+Hash: e4e6b33f7dfaa2a528d06a050f5b6c9cb1cd061d
+Date: 2026-06-17T10:41:44+02:00
+Description: test: add source project compatibility fixtures
+
+## 007 - Document Migration Path
+
+Status: complete
+
+- Added README migration documentation covering installation, local dependency declaration, import replacement, default-template directory configuration, supported legacy public functions, and recursive completion behavior.
+- Documented that consuming projects keep their own YAML templates and pass `default_files_dir` or `default_template_dir` explicitly.
+- Called out preservation of existing user values, preservation of extra keys, scalar-versus-dictionary conflict behavior, `force_default=True`, and `complete_file=False`.
+- Added a README regression test that checks the migration guide includes the issue's required topics.
+
+## 008 - Review Template Discovery Compatibility Decision
+
+Status: complete
+
+- Documented the public template-discovery decision in the README.
+- Chose explicit `default_files_dir` or `default_template_dir` configuration for the first stable API.
+- Explained why `conveoconfi` cannot rely on its own package `default_files` directory for consuming project templates.
+- Evaluated caller-package inference as a possible compatibility helper and kept it out of scope because explicit paths are more predictable and already covered by the current API.
+- Added a README regression test for the template-discovery decision.

conveoconfi-0.1.0/.agents/code-standards/conventional-commits-messages.md

@@ -0,0 +1,131 @@
+
+# Conventional Commits 1.0.0
+
+## Summary
+
+The Conventional Commits specification is a lightweight convention on top of commit messages.
+It provides an easy set of rules for creating an explicit commit history;
+which makes it easier to write automated tools on top of.
+This convention dovetails with [SemVer](http://semver.org),
+by describing the features, fixes, and breaking changes made in commit messages.
+
+The commit message should be structured as follows:
+
+---
+
+```
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+---
+
+<br />
+The commit contains the following structural elements, to communicate intent to the
+consumers of your library:
+
+1. **fix:** a commit of the _type_ `fix` patches a bug in your codebase (this correlates with [`PATCH`](http://semver.org/#summary) in Semantic Versioning).
+1. **feat:** a commit of the _type_ `feat` introduces a new feature to the codebase (this correlates with [`MINOR`](http://semver.org/#summary) in Semantic Versioning).
+1. **BREAKING CHANGE:** a commit that has a footer `BREAKING CHANGE:`, or appends a `!` after the type/scope, introduces a breaking API change (correlating with [`MAJOR`](http://semver.org/#summary) in Semantic Versioning).
+A BREAKING CHANGE can be part of commits of any _type_.
+1. _types_ other than `fix:` and `feat:` are allowed, for example [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (based on the [Angular convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) recommends `build:`, `chore:`,
+  `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, and others.
+1. _footers_ other than `BREAKING CHANGE: <description>` may be provided and follow a convention similar to
+  [git trailer format](https://git-scm.com/docs/git-interpret-trailers).
+
+Additional types are not mandated by the Conventional Commits specification, and have no implicit effect in Semantic Versioning (unless they include a BREAKING CHANGE).
+<br /><br />
+A scope may be provided to a commit's type, to provide additional contextual information and is contained within parenthesis, e.g., `feat(parser): add ability to parse arrays`.
+
+## Examples
+
+### Commit message with description and breaking change footer
+```
+feat: allow provided config object to extend other configs
+
+BREAKING CHANGE: `extends` key in config file is now used for extending other config files
+```
+
+### Commit message with `!` to draw attention to breaking change
+```
+feat!: send an email to the customer when a product is shipped
+```
+
+### Commit message with scope and `!` to draw attention to breaking change
+```
+feat(api)!: send an email to the customer when a product is shipped
+```
+
+### Commit message with both `!` and BREAKING CHANGE footer
+```
+feat!: drop support for Node 6
+
+BREAKING CHANGE: use JavaScript features not available in Node 6.
+```
+
+### Commit message with no body
+```
+docs: correct spelling of CHANGELOG
+```
+
+### Commit message with scope
+```
+feat(lang): add Polish language
+```
+
+### Commit message with multi-paragraph body and multiple footers
+```
+fix: prevent racing of requests
+
+Introduce a request id and a reference to latest request. Dismiss
+incoming responses other than from latest request.
+
+Remove timeouts which were used to mitigate the racing issue but are
+obsolete now.
+
+Reviewed-by: Z
+Refs: #123
+```
+
+## Specification
+
+The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).
+
+1. Commits MUST be prefixed with a type, which consists of a noun, `feat`, `fix`, etc., followed
+  by the OPTIONAL scope, OPTIONAL `!`, and REQUIRED terminal colon and space.
+1. The type `feat` MUST be used when a commit adds a new feature to your application or library.
+1. The type `fix` MUST be used when a commit represents a bug fix for your application.
+1. A scope MAY be provided after a type. A scope MUST consist of a noun describing a
+  section of the codebase surrounded by parenthesis, e.g., `fix(parser):`
+1. A description MUST immediately follow the colon and space after the type/scope prefix.
+The description is a short summary of the code changes, e.g., _fix: array parsing issue when multiple spaces were contained in string_.
+1. A longer commit body MAY be provided after the short description, providing additional contextual information about the code changes. The body MUST begin one blank line after the description.
+1. A commit body is free-form and MAY consist of any number of newline separated paragraphs.
+1. One or more footers MAY be provided one blank line after the body. Each footer MUST consist of
+ a word token, followed by either a `:<space>` or `<space>#` separator, followed by a string value (this is inspired by the
+  [git trailer convention](https://git-scm.com/docs/git-interpret-trailers)).
+1. A footer's token MUST use `-` in place of whitespace characters, e.g., `Acked-by` (this helps differentiate
+  the footer section from a multi-paragraph body). An exception is made for `BREAKING CHANGE`, which MAY also be used as a token.
+1. A footer's value MAY contain spaces and newlines, and parsing MUST terminate when the next valid footer
+  token/separator pair is observed.
+1. Breaking changes MUST be indicated in the type/scope prefix of a commit, or as an entry in the
+  footer.
+1. If included as a footer, a breaking change MUST consist of the uppercase text BREAKING CHANGE, followed by a colon, space, and description, e.g.,
+_BREAKING CHANGE: environment variables now take precedence over config files_.
+1. If included in the type/scope prefix, breaking changes MUST be indicated by a
+  `!` immediately before the `:`. If `!` is used, `BREAKING CHANGE:` MAY be omitted from the footer section,
+  and the commit description SHALL be used to describe the breaking change.
+1. Types other than `feat` and `fix` MAY be used in your commit messages, e.g., _docs: update ref docs._
+1. The units of information that make up Conventional Commits MUST NOT be treated as case-sensitive by implementors, with the exception of BREAKING CHANGE which MUST be uppercase.
+1. BREAKING-CHANGE MUST be synonymous with BREAKING CHANGE, when used as a token in a footer.
+
+## Why Use Conventional Commits
+
+* Automatically generating CHANGELOGs.
+* Automatically determining a semantic version bump (based on the types of commits landed).
+* Communicating the nature of changes to teammates, the public, and other stakeholders.
+* Triggering build and publish processes.
+* Making it easier for people to contribute to your projects, by allowing them to explore
+  a more structured commit history.

conveoconfi-0.1.0/.agents/issues/001-bootstrap-importable-library-package.md

@@ -0,0 +1,30 @@
+## What to build
+
+Bootstrap `conveoconfi` as an importable Python library package with PyYAML declared as a dependency and a minimal public API entrypoint ready to expose the legacy config-file functions.
+
+## Acceptance criteria
+
+- [x] `conveoconfi` can be imported from the project test environment.
+- [x] Package metadata identifies the project as a Python library and declares the YAML dependency needed by the compatibility API.
+- [x] The public package entrypoint is ready to expose the legacy function names without requiring consumers to import from private modules.
+- [x] A basic test verifies the package import path works.
+
+## Blocked by
+
+None - can start immediately
+
+## Type
+
+AFK
+
+## User stories covered
+
+1, 5, 6, 34, 36
+
+## Latest Git Reference for this file
+
+Latest commit when this document was written:
+
+Hash: f00456aa2bca301d4d07852bb6e580fb0b311135
+Date: 2026-06-17T10:19:33+02:00
+Description: feat: bootstrap importable library package

conveoconfi-0.1.0/.agents/issues/002-create-config-files-from-project-templates.md

@@ -0,0 +1,24 @@
+## What to build
+
+Implement the first end-to-end convention-over-configuration path: a consuming project can point `conveoconfi` at its own default YAML templates, request a config file, and receive parsed config data while the missing or empty app config file is created from the matching template.
+
+## Acceptance criteria
+
+- [x] A missing app config directory is created automatically when a config file path is resolved.
+- [x] A missing config file is created from the matching project-provided default YAML template.
+- [x] An existing empty YAML config file is replaced with default template content and returned as parsed data.
+- [x] Template lookup failures produce explicit, diagnosable errors.
+- [x] YAML is loaded with safe parsing and written in a human-readable format.
+- [x] Tests cover missing file creation, empty file recovery, returned parsed data, and explicit template-directory use.
+
+## Blocked by
+
+- 001-bootstrap-importable-library-package.md
+
+## Type
+
+AFK
+
+## User stories covered
+
+7, 8, 9, 18, 25, 26, 27, 28, 32, 40

conveoconfi-0.1.0/.agents/issues/003-complete-existing-config-files-recursively.md

@@ -0,0 +1,26 @@
+## What to build
+
+Extend the config read path so existing config files are completed from their default templates, including nested dictionary keys, while preserving all user-provided values and extra keys.
+
+## Acceptance criteria
+
+- [x] Missing top-level keys are copied from the default template into the current config file.
+- [x] Missing nested dictionary keys are copied from the default template into the current config file.
+- [x] Existing user-provided values are preserved during completion.
+- [x] User-defined extra keys not present in the default template are preserved.
+- [x] Scalar-versus-dictionary conflicts preserve the current user value rather than replacing it implicitly.
+- [x] `force_default=True` overwrites an existing config file with defaults.
+- [x] `complete_file=False` reads an incomplete existing config file without mutating it.
+- [x] Tests cover recursive completion, preservation rules, force-default behavior, and no-mutation reads.
+
+## Blocked by
+
+- 002-create-config-files-from-project-templates.md
+
+## Type
+
+AFK
+
+## User stories covered
+
+10, 11, 12, 13, 14, 15, 16, 17, 30, 37, 38, 39

conveoconfi-0.1.0/.agents/issues/004-preserve-legacy-file-operations.md

@@ -0,0 +1,24 @@
+## What to build
+
+Preserve the legacy filesystem operations used by the source projects: overwriting YAML config files, append-normalizing YAML data, checking config-file existence, and returning config-file paths while keeping app-directory creation behavior.
+
+## Acceptance criteria
+
+- [x] `overwrite_config_file` writes readable YAML data to the requested app config file.
+- [x] `append_config_file` appends YAML data, reloads the file, and rewrites normalized YAML so repeated appended content is not duplicated.
+- [x] `append_config_file` preserves Unicode values.
+- [x] `config_file_exists` returns false before creation and true after the file exists.
+- [x] `config_file_path` returns the expected file path and ensures the app config directory exists.
+- [x] Tests use temporary directories and real files for all filesystem behavior.
+
+## Blocked by
+
+- 002-create-config-files-from-project-templates.md
+
+## Type
+
+AFK
+
+## User stories covered
+
+19, 20, 23, 24, 29, 31

conveoconfi-0.1.0/.agents/issues/005-preserve-legacy-parameter-reads.md

@@ -0,0 +1,31 @@
+## What to build
+
+Implement the legacy parameter read path so consuming wrappers can call `get_param(parent_param, param, default_app_dir)` and read child values from `config.yaml` with the same missing-parameter behavior as the old modules.
+
+## Acceptance criteria
+
+- [x] `get_param` reads `config.yaml` through the same create/read/complete behavior as other config files.
+- [x] `get_param` returns the requested child value from the requested parent section.
+- [x] Missing child parameters raise an exception with the legacy message shape.
+- [x] Tests cover successful reads and missing child parameter errors.
+
+## Blocked by
+
+- 003-complete-existing-config-files-recursively.md
+- 004-preserve-legacy-file-operations.md
+
+## Type
+
+AFK
+
+## User stories covered
+
+21, 22
+
+## Latest Git Reference for this file
+
+Latest commit when this document was written:
+
+Hash: ee84a8cd5952f83fa63a1faa47d919db7a4fa00e
+Date: 2026-06-17T10:37:16+02:00
+Description: feat: preserve legacy parameter reads

conveoconfi-0.1.0/.agents/issues/006-add-source-project-compatibility-fixtures.md

@@ -0,0 +1,31 @@
+## What to build
+
+Add compatibility tests using representative default YAML shapes from `cheapchocolate`, `ohmyscrapper`, and `aphantasist` to prove the reusable library can replace each project's duplicated `config_files.py` behavior.
+
+## Acceptance criteria
+
+- [x] A `cheapchocolate`-style config fixture verifies nested completion preserves existing nested values and adds missing nested defaults.
+- [x] An `ohmyscrapper`-style config fixture verifies project-specific sections such as `db`, `default_dirs`, `default_files`, `ai`, `sniffing`, and `queue` can be created and completed.
+- [x] An `aphantasist`-style config fixture verifies simple default config files continue to work.
+- [x] Fixture tests exercise the public compatibility API rather than private helpers.
+- [x] Tests document the upstream reference commits used for fixture behavior.
+
+## Blocked by
+
+- 005-preserve-legacy-parameter-reads.md
+
+## Type
+
+AFK
+
+## User stories covered
+
+2, 3, 4, 33
+
+## Latest Git Reference for this file
+
+Latest commit when this document was written:
+
+Hash: e4e6b33f7dfaa2a528d06a050f5b6c9cb1cd061d
+Date: 2026-06-17T10:41:44+02:00
+Description: test: add source project compatibility fixtures

conveoconfi-0.1.0/.agents/issues/007-document-migration-path.md

@@ -0,0 +1,23 @@
+## What to build
+
+Document how maintainers migrate from duplicated project-local `core.config_files` modules to the shared `conveoconfi` dependency, including installation, import replacement, default-template setup, and removal of the old module.
+
+## Acceptance criteria
+
+- [x] Documentation shows how to install or declare `conveoconfi` as a dependency.
+- [x] Documentation shows the import replacement from project-local `core.config_files` to the new package.
+- [x] Documentation explains how consuming projects provide or configure their default YAML template directory.
+- [x] Documentation lists the legacy public functions supported by the compatibility API.
+- [x] Documentation calls out recursive completion and preservation of existing user config values.
+
+## Blocked by
+
+- 005-preserve-legacy-parameter-reads.md
+
+## Type
+
+AFK
+
+## User stories covered
+
+2, 3, 4, 25, 26, 35

conveoconfi-0.1.0/.agents/issues/008-review-template-discovery-compatibility-decision.md

@@ -0,0 +1,36 @@
+## What to build
+
+Review and confirm the final migration ergonomics for default-template discovery before the public API is considered stable: explicit template directory or configuration object only, or an additional compatibility helper that can infer defaults from caller package context.
+
+## Acceptance criteria
+
+- [x] The chosen template-discovery approach is documented as a public API decision.
+- [x] The decision explains why the library cannot rely on its own package `default_files` directory for consuming project templates.
+- [x] The decision evaluates explicit template-directory configuration against any compatibility helper.
+- [x] Follow-up implementation issues are created or updated if the decision changes the existing issue scope.
+
+## Decision
+
+Keep the first stable public API explicit: consuming projects pass their
+template directory with `default_files_dir` or `default_template_dir`.
+`conveoconfi` will not infer templates from its own package `default_files`
+directory because the reusable dependency cannot contain each consuming
+application's YAML defaults.
+
+A caller-package inference helper was considered, but it would add layout
+assumptions and ambiguity to the migration path. The existing explicit API is
+more predictable, easier to test, and already produces direct lookup errors when
+templates are omitted or missing. No follow-up implementation issue is needed
+because the current issue scope remains unchanged.
+
+## Blocked by
+
+- 002-create-config-files-from-project-templates.md
+
+## Type
+
+HITL
+
+## User stories covered
+
+25, 26, 40