dreamcatcher 5.5.0__tar.gz

dreamcatcher-5.5.0/.agents/skills/uncoded-code-navigation/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: uncoded-code-navigation
+description: Load once per session, before the first search, read, or edit of Python source in a codebase indexed by uncoded. Covers locating a symbol, reading a definition, or checking references before you refactor, rename, or delete.
+---
+
+<!-- Generated by uncoded — do not edit; regeneration overwrites. -->
+
+# Code Navigation
+
+This codebase uses [uncoded](https://github.com/alimanfoo/uncoded) to maintain a
+symbol index over its source code, with two associated CLI tools: `uncoded body`
+for reading a symbol's body and `uncoded refs` for finding references.
+
+## The dispatch rule
+
+**If your search term is the name of a Python symbol, use the index. Python
+symbols are classes, functions, methods, attributes, and module-level constants.
+If it's a pattern, regex, or free-text phrase, use grep.**
+
+This dispatch rule applies to every tool call where you find code, not just the
+first in the session. The pretrained reflex for "find X" is grep, and that
+reflex is wrong here. Reaching for `grep -rn 'def parse_config'` to read a
+function's body is a case for `uncoded body`. Reaching for
+`grep -rn 'validate_input'` to check callers before a refactor is a case for
+`uncoded refs`. Reaching for `grep` then `Edit` to delete dead code is a case
+for `uncoded refs` to confirm the code is dead, then `Edit`. The grep version of
+any of these is noisier and less reliable. Grep matches comments, strings, and
+unrelated attributes. Grep misses re-exports, so caller and delete checks come
+back incomplete. Grep forces offset arithmetic to slice a body. The indexed
+tools don't.
+
+## How to execute the rule
+
+The index has two parts: a namespace map and per-file stubs. Follow this
+sequence.
+
+**Step 1: Orient. Read the namespace map first.** If the map is missing, run the
+repository's configured `uncoded sync` command. Then, before answering the user,
+before any other tool call:
+
+```text
+Read .uncoded/namespace.yaml
+```
+
+This lists every symbol in the codebase: directories, files, classes, methods,
+functions. Without it loaded, "find X" answers come from pretrained guesses.
+They reflect what a project like this probably contains, not what is actually
+here. Read it once, in full, at session start.
+
+**Step 2: Understand. Read the `.pyi` stub before any `.py` source.** Stub paths
+mirror source paths under `.uncoded/stubs/`:
+
+```text
+src/foo/bar.py      →  .uncoded/stubs/src/foo/bar.pyi
+tests/test_foo.py   →  .uncoded/stubs/tests/test_foo.pyi
+```
+
+Read the stub for every file you intend to touch or reference, including tests.
+The stub contains imports, every signature with types, module-level assignments,
+and class attributes. That is enough for most navigation. Skipping straight to
+source means reading many lines to learn what the stub would have told you in
+one. If no stub exists at the expected path, the file has no symbols indexed. In
+that narrow case, read source directly.
+
+**Step 3: Act.** Use `uncoded body` to read a symbol's body. Use `uncoded refs`
+to find every reference to a symbol. Use `Edit` (with `uncoded body`'s output as
+`old_string`) to change a symbol. With the map and stub loaded, you have the
+exact `relative_path` and `name_path` each tool needs. Use `ClassName/method`
+for a method and `function_name` for a top-level function. Per task:
+
+- **Read a symbol's body.** `uvx uncoded body <name_path> --in <relative_path>`
+  prints the symbol's source text to stdout, byte-identical to disk. Returns
+  exactly the symbol. No offset arithmetic, no risk of reading too much. Its
+  output has every byte `Edit` needs as `old_string`. You need no extra `Read`
+  for partial edits. Stay on stubs for a wider sweep.
+
+- **Find every reference to a symbol.**
+  `uvx uncoded refs <name_path> --in <relative_path>`. Prints one reference per
+  line as `<path>:<line>:<col>`, sorted by path, then line, then column. Each
+  path is relative to the current working directory when possible and otherwise
+  absolute. Grep on the name misses re-exports and adds false positives from
+  comments, strings, and attribute lookups on other types. If the next move
+  depends on the answer being complete, grep cannot give you that.
+
+- **Edit a symbol.** `uvx uncoded body <name_path> --in <relative_path>` gives
+  the exact `old_string`; then `Edit` to apply the change.
+
+- **Rename.** `uvx uncoded refs <name_path> --in <relative_path>` enumerates
+  every site; then `Edit` at each.
+
+- **Safely delete.** `uvx uncoded refs <name_path> --in <relative_path>` must
+  return empty; then `Edit` to remove.
+
+**Step 4: Refresh.** After every modification to indexed Python source, run the
+repository's configured `uncoded sync` command before the next code-navigation
+operation. The modification can change the namespace map and stubs.
+
+## Where Read, Edit, and grep are still the right tools
+
+The rule is about source navigation by symbol name. Outside that, Read, Edit,
+and grep stay correct:
+
+- Free-text or pattern search outside source: Markdown, YAML, TOML, configs,
+  commit messages, notebook JSON, fixture data.
+- Pattern search across signatures (regex over type annotations, decorator
+  usage, alias declarations). These are not symbol-name lookups, even though
+  they sit inside source.
+- Partial-line edits inside a symbol body, once you have retrieved it via
+  `uncoded body`.
+- The rare stub-less Python file that needs exploratory reading.
+
+The dispatch rule turns on the search term. A symbol name goes to the index. A
+regex or free-text phrase goes to grep.

dreamcatcher-5.5.0/.agents/skills/uncoded-consistency-review/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: uncoded-consistency-review
+description: Review a Python codebase for semantic and naming consistency. It reports only concrete disagreements between two claims about the same concept, with verbatim evidence for each claim. It assumes uncoded is installed (.uncoded/namespace.yaml and .uncoded/stubs/ present).
+---
+
+<!-- Generated by uncoded — do not edit; regeneration overwrites. -->
+
+# Semantic Consistency Review
+
+Review a Python codebase for concrete disagreements in its vocabulary and symbol
+contracts. A finding must identify two claims about the same concept that ought
+to agree, but do not.
+
+## Guardrails
+
+Admit a finding only when the codebase supports both claims, their observable
+difference, and the reason that they should agree. Quote both claims verbatim.
+Omit a candidate when either claim or the reason for comparing them is
+unsupported.
+
+Review semantic and naming consistency, not formatting or style consistency. Do
+not report general bugs, complexity, performance, security, or design
+preferences unless they appear as a disagreement between two supported claims.
+Do not report overgrown public surfaces, private imports, cross-domain imports,
+zero-reference symbols, or redundant public surfaces merely because they exist.
+
+## Prerequisites
+
+Run the repository's configured `uncoded sync` command. Read the repository's
+agent instructions and follow its navigation rules.
+
+## Orientation
+
+Read `.uncoded/namespace.yaml` in full. Use its package structure and symbol
+names to map the codebase's main concepts and vocabulary.
+
+## Vocabulary sweep
+
+Use the namespace and stubs to find candidates, then confirm semantic overlap
+from signatures, docstrings, or bodies. Look for:
+
+- **Competing terms:** different names for substantively the same concept.
+- **Conflicting use:** the same term used incompatibly within a shared context.
+- **Stale qualifiers:** names such as `legacy`, `v2`, or `final` whose
+  distinction conflicts with another symbol or a symbol's docstring.
+
+Similar spelling, low vocabulary overlap, or the presence of a qualifier is not
+evidence on its own. A finding needs two concrete claims that establish the
+shared concept and the disagreement.
+
+## Symbol-contract sweep
+
+Compare a symbol's name, signature, docstring, and, when needed, behaviour.
+Findings may cover:
+
+- name-signature disagreement
+- name-docstring disagreement
+- docstring-signature disagreement
+- name-behaviour disagreement
+
+Read each relevant source file's stub for names and signatures. Run the
+repository's configured `uncoded body` command only when a docstring or
+implementation is needed to confirm a candidate. Do not retrieve every symbol
+body.
+
+## Report
+
+Return the report directly as the final turn output.
+
+Use this structure:
+
+```markdown
+## Semantic Consistency Review
+
+### Scope
+
+<What was reviewed and intentionally omitted.>
+
+### Summary
+
+<Two or three sentences that summarise the supported findings.>
+
+### Vocabulary findings
+
+#### 1. <Summary>
+
+**Claim A** — `<path>` · `<symbol>` · name | signature | docstring | body
+
+> Verbatim evidence
+
+**Claim B** — `<path>` · `<symbol>` · name | signature | docstring | body
+
+> Verbatim evidence
+
+**How they differ:** <The observable disagreement.>
+
+**Why these should agree:** <Evidence that both claims describe the same
+concept.>
+
+### Symbol-contract findings
+
+#### 1. <Summary>
+
+<Use the same finding structure.>
+```
+
+Keep both finding headings. If a group has no supported findings, state that
+under its heading. Number findings independently within each group.
+
+## Examples
+
+### Vocabulary finding
+
+#### 1. Customer lookup uses competing verbs
+
+**Claim A** — `storage.py` · `fetch_customer` · signature
+
+> `fetch_customer(customer_id: str) -> Customer`
+
+**Claim B** — `adapter.py` · `load_customer` · signature
+
+> `load_customer(customer_id: str) -> Customer`
+
+**How they differ:** The same lookup uses `fetch` in one module and `load` in
+another.
+
+**Why these should agree:** Both signatures accept a customer ID and return a
+customer through sibling adapters.
+
+### Symbol-contract finding
+
+#### 1. Predicate name promises a boolean but returns a value
+
+**Claim A** — `cache.py` · `is_cached` · name
+
+> `is_cached`
+
+**Claim B** — `cache.py` · `is_cached` · signature
+
+> `is_cached(key: str) -> str | None`
+
+**How they differ:** The name promises a predicate, while the return type holds
+a cached value or absence.
+
+**Why these should agree:** Both claims describe the contract of `is_cached`.

dreamcatcher-5.5.0/.agents/skills/uncoded-doc-navigation/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: uncoded-doc-navigation
+description: Load once per session, before the first search or read of a codebase's Markdown documentation indexed by uncoded. Covers locating which file and section cover a topic, or orienting to what documentation exists.
+---
+
+<!-- Generated by uncoded — do not edit; regeneration overwrites. -->
+
+# Documentation Navigation
+
+This codebase uses [uncoded](https://github.com/alimanfoo/uncoded) to maintain a
+documentation index.
+
+**Step 1: Orient. Read the docs map first.** If the map is missing, run the
+repository's configured `uncoded sync` command. Then, before answering the user,
+before any other tool call:
+
+```text
+Read .uncoded/docs.yaml
+```
+
+`.uncoded/docs.yaml` is an orientation outline: it lists every Markdown file and
+its heading hierarchy. Read it once, in full, at session start.
+
+**Step 2: Navigate.** Headings in the map are literal text. Use `Read` or `grep`
+to navigate to a specific section identified in the map.
+
+**Step 3: Refresh.** After every modification to indexed Markdown, run the
+repository's configured `uncoded sync` command before the next
+documentation-navigation operation. The modification can change the heading map.

dreamcatcher-5.5.0/.claude/skills/uncoded-code-navigation/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: uncoded-code-navigation
+description: Load once per session, before the first search, read, or edit of Python source in a codebase indexed by uncoded. Covers locating a symbol, reading a definition, or checking references before you refactor, rename, or delete.
+---
+
+<!-- Generated by uncoded — do not edit; regeneration overwrites. -->
+
+# Code Navigation
+
+This codebase uses [uncoded](https://github.com/alimanfoo/uncoded) to maintain a
+symbol index over its source code, with two associated CLI tools: `uncoded body`
+for reading a symbol's body and `uncoded refs` for finding references.
+
+## The dispatch rule
+
+**If your search term is the name of a Python symbol, use the index. Python
+symbols are classes, functions, methods, attributes, and module-level constants.
+If it's a pattern, regex, or free-text phrase, use grep.**
+
+This dispatch rule applies to every tool call where you find code, not just the
+first in the session. The pretrained reflex for "find X" is grep, and that
+reflex is wrong here. Reaching for `grep -rn 'def parse_config'` to read a
+function's body is a case for `uncoded body`. Reaching for
+`grep -rn 'validate_input'` to check callers before a refactor is a case for
+`uncoded refs`. Reaching for `grep` then `Edit` to delete dead code is a case
+for `uncoded refs` to confirm the code is dead, then `Edit`. The grep version of
+any of these is noisier and less reliable. Grep matches comments, strings, and
+unrelated attributes. Grep misses re-exports, so caller and delete checks come
+back incomplete. Grep forces offset arithmetic to slice a body. The indexed
+tools don't.
+
+## How to execute the rule
+
+The index has two parts: a namespace map and per-file stubs. Follow this
+sequence.
+
+**Step 1: Orient. Read the namespace map first.** If the map is missing, run the
+repository's configured `uncoded sync` command. Then, before answering the user,
+before any other tool call:
+
+```text
+Read .uncoded/namespace.yaml
+```
+
+This lists every symbol in the codebase: directories, files, classes, methods,
+functions. Without it loaded, "find X" answers come from pretrained guesses.
+They reflect what a project like this probably contains, not what is actually
+here. Read it once, in full, at session start.
+
+**Step 2: Understand. Read the `.pyi` stub before any `.py` source.** Stub paths
+mirror source paths under `.uncoded/stubs/`:
+
+```text
+src/foo/bar.py      →  .uncoded/stubs/src/foo/bar.pyi
+tests/test_foo.py   →  .uncoded/stubs/tests/test_foo.pyi
+```
+
+Read the stub for every file you intend to touch or reference, including tests.
+The stub contains imports, every signature with types, module-level assignments,
+and class attributes. That is enough for most navigation. Skipping straight to
+source means reading many lines to learn what the stub would have told you in
+one. If no stub exists at the expected path, the file has no symbols indexed. In
+that narrow case, read source directly.
+
+**Step 3: Act.** Use `uncoded body` to read a symbol's body. Use `uncoded refs`
+to find every reference to a symbol. Use `Edit` (with `uncoded body`'s output as
+`old_string`) to change a symbol. With the map and stub loaded, you have the
+exact `relative_path` and `name_path` each tool needs. Use `ClassName/method`
+for a method and `function_name` for a top-level function. Per task:
+
+- **Read a symbol's body.** `uvx uncoded body <name_path> --in <relative_path>`
+  prints the symbol's source text to stdout, byte-identical to disk. Returns
+  exactly the symbol. No offset arithmetic, no risk of reading too much. Its
+  output has every byte `Edit` needs as `old_string`. You need no extra `Read`
+  for partial edits. Stay on stubs for a wider sweep.
+
+- **Find every reference to a symbol.**
+  `uvx uncoded refs <name_path> --in <relative_path>`. Prints one reference per
+  line as `<path>:<line>:<col>`, sorted by path, then line, then column. Each
+  path is relative to the current working directory when possible and otherwise
+  absolute. Grep on the name misses re-exports and adds false positives from
+  comments, strings, and attribute lookups on other types. If the next move
+  depends on the answer being complete, grep cannot give you that.
+
+- **Edit a symbol.** `uvx uncoded body <name_path> --in <relative_path>` gives
+  the exact `old_string`; then `Edit` to apply the change.
+
+- **Rename.** `uvx uncoded refs <name_path> --in <relative_path>` enumerates
+  every site; then `Edit` at each.
+
+- **Safely delete.** `uvx uncoded refs <name_path> --in <relative_path>` must
+  return empty; then `Edit` to remove.
+
+**Step 4: Refresh.** After every modification to indexed Python source, run the
+repository's configured `uncoded sync` command before the next code-navigation
+operation. The modification can change the namespace map and stubs.
+
+## Where Read, Edit, and grep are still the right tools
+
+The rule is about source navigation by symbol name. Outside that, Read, Edit,
+and grep stay correct:
+
+- Free-text or pattern search outside source: Markdown, YAML, TOML, configs,
+  commit messages, notebook JSON, fixture data.
+- Pattern search across signatures (regex over type annotations, decorator
+  usage, alias declarations). These are not symbol-name lookups, even though
+  they sit inside source.
+- Partial-line edits inside a symbol body, once you have retrieved it via
+  `uncoded body`.
+- The rare stub-less Python file that needs exploratory reading.
+
+The dispatch rule turns on the search term. A symbol name goes to the index. A
+regex or free-text phrase goes to grep.

dreamcatcher-5.5.0/.claude/skills/uncoded-consistency-review/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: uncoded-consistency-review
+description: Review a Python codebase for semantic and naming consistency. It reports only concrete disagreements between two claims about the same concept, with verbatim evidence for each claim. It assumes uncoded is installed (.uncoded/namespace.yaml and .uncoded/stubs/ present).
+---
+
+<!-- Generated by uncoded — do not edit; regeneration overwrites. -->
+
+# Semantic Consistency Review
+
+Review a Python codebase for concrete disagreements in its vocabulary and symbol
+contracts. A finding must identify two claims about the same concept that ought
+to agree, but do not.
+
+## Guardrails
+
+Admit a finding only when the codebase supports both claims, their observable
+difference, and the reason that they should agree. Quote both claims verbatim.
+Omit a candidate when either claim or the reason for comparing them is
+unsupported.
+
+Review semantic and naming consistency, not formatting or style consistency. Do
+not report general bugs, complexity, performance, security, or design
+preferences unless they appear as a disagreement between two supported claims.
+Do not report overgrown public surfaces, private imports, cross-domain imports,
+zero-reference symbols, or redundant public surfaces merely because they exist.
+
+## Prerequisites
+
+Run the repository's configured `uncoded sync` command. Read the repository's
+agent instructions and follow its navigation rules.
+
+## Orientation
+
+Read `.uncoded/namespace.yaml` in full. Use its package structure and symbol
+names to map the codebase's main concepts and vocabulary.
+
+## Vocabulary sweep
+
+Use the namespace and stubs to find candidates, then confirm semantic overlap
+from signatures, docstrings, or bodies. Look for:
+
+- **Competing terms:** different names for substantively the same concept.
+- **Conflicting use:** the same term used incompatibly within a shared context.
+- **Stale qualifiers:** names such as `legacy`, `v2`, or `final` whose
+  distinction conflicts with another symbol or a symbol's docstring.
+
+Similar spelling, low vocabulary overlap, or the presence of a qualifier is not
+evidence on its own. A finding needs two concrete claims that establish the
+shared concept and the disagreement.
+
+## Symbol-contract sweep
+
+Compare a symbol's name, signature, docstring, and, when needed, behaviour.
+Findings may cover:
+
+- name-signature disagreement
+- name-docstring disagreement
+- docstring-signature disagreement
+- name-behaviour disagreement
+
+Read each relevant source file's stub for names and signatures. Run the
+repository's configured `uncoded body` command only when a docstring or
+implementation is needed to confirm a candidate. Do not retrieve every symbol
+body.
+
+## Report
+
+Return the report directly as the final turn output.
+
+Use this structure:
+
+```markdown
+## Semantic Consistency Review
+
+### Scope
+
+<What was reviewed and intentionally omitted.>
+
+### Summary
+
+<Two or three sentences that summarise the supported findings.>
+
+### Vocabulary findings
+
+#### 1. <Summary>
+
+**Claim A** — `<path>` · `<symbol>` · name | signature | docstring | body
+
+> Verbatim evidence
+
+**Claim B** — `<path>` · `<symbol>` · name | signature | docstring | body
+
+> Verbatim evidence
+
+**How they differ:** <The observable disagreement.>
+
+**Why these should agree:** <Evidence that both claims describe the same
+concept.>
+
+### Symbol-contract findings
+
+#### 1. <Summary>
+
+<Use the same finding structure.>
+```
+
+Keep both finding headings. If a group has no supported findings, state that
+under its heading. Number findings independently within each group.
+
+## Examples
+
+### Vocabulary finding
+
+#### 1. Customer lookup uses competing verbs
+
+**Claim A** — `storage.py` · `fetch_customer` · signature
+
+> `fetch_customer(customer_id: str) -> Customer`
+
+**Claim B** — `adapter.py` · `load_customer` · signature
+
+> `load_customer(customer_id: str) -> Customer`
+
+**How they differ:** The same lookup uses `fetch` in one module and `load` in
+another.
+
+**Why these should agree:** Both signatures accept a customer ID and return a
+customer through sibling adapters.
+
+### Symbol-contract finding
+
+#### 1. Predicate name promises a boolean but returns a value
+
+**Claim A** — `cache.py` · `is_cached` · name
+
+> `is_cached`
+
+**Claim B** — `cache.py` · `is_cached` · signature
+
+> `is_cached(key: str) -> str | None`
+
+**How they differ:** The name promises a predicate, while the return type holds
+a cached value or absence.
+
+**Why these should agree:** Both claims describe the contract of `is_cached`.

dreamcatcher-5.5.0/.claude/skills/uncoded-doc-navigation/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: uncoded-doc-navigation
+description: Load once per session, before the first search or read of a codebase's Markdown documentation indexed by uncoded. Covers locating which file and section cover a topic, or orienting to what documentation exists.
+---
+
+<!-- Generated by uncoded — do not edit; regeneration overwrites. -->
+
+# Documentation Navigation
+
+This codebase uses [uncoded](https://github.com/alimanfoo/uncoded) to maintain a
+documentation index.
+
+**Step 1: Orient. Read the docs map first.** If the map is missing, run the
+repository's configured `uncoded sync` command. Then, before answering the user,
+before any other tool call:
+
+```text
+Read .uncoded/docs.yaml
+```
+
+`.uncoded/docs.yaml` is an orientation outline: it lists every Markdown file and
+its heading hierarchy. Read it once, in full, at session start.
+
+**Step 2: Navigate.** Headings in the map are literal text. Use `Read` or `grep`
+to navigate to a specific section identified in the map.
+
+**Step 3: Refresh.** After every modification to indexed Markdown, run the
+repository's configured `uncoded sync` command before the next
+documentation-navigation operation. The modification can change the heading map.

dreamcatcher-5.5.0/.gitattributes

@@ -0,0 +1,17 @@
+# Collapse generated files in a diff, and keep them out of the language
+# statistics. uncoded writes the skills; uv writes the lock.
+.claude/skills/** linguist-generated=true
+.agents/skills/** linguist-generated=true
+uv.lock linguist-generated=true
+
+# A recorded stream is read back byte for byte by a golden test, so no checkout
+# rewrites its line endings.
+tests/fixtures/** -text
+
+# Vendored release files are checked against upstream by checksum, so a
+# checkout must not rewrite their line endings.
+src/dreamcatcher/static/vendor/** -text
+
+# init writes the default configuration into a user's checkout as it is here,
+# so no checkout rewrites its line endings.
+src/dreamcatcher/default_config.toml text eol=lf

dreamcatcher-5.5.0/.github/dependabot.yml

@@ -0,0 +1,38 @@
+version: 2
+
+# Each ecosystem opens one pull request for its version updates and one for
+# its security updates, majors included, because a group applies to one kind.
+
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      uv:
+        patterns: ["*"]
+      uv-security:
+        applies-to: security-updates
+        patterns: ["*"]
+
+  - package-ecosystem: "pre-commit"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      pre-commit:
+        patterns: ["*"]
+      pre-commit-security:
+        applies-to: security-updates
+        patterns: ["*"]
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      github-actions:
+        patterns: ["*"]
+      github-actions-security:
+        applies-to: security-updates
+        patterns: ["*"]