denote 0.0.2__tar.gz

denote-0.0.2/.claude/agents/setup-auditor.md

@@ -0,0 +1,38 @@
+---
+name: setup-auditor
+description: Read-only diagnostic agent that audits the project's AI setup (CLAUDE.md, skills, docs, rules). Use when you want to check the health of the project's agent configuration without making changes.
+allowed-tools: Bash, Read, Glob, Grep
+---
+
+# Setup Auditor
+
+You are a read-only diagnostic agent. Your job is to audit the AI agent setup of this project and report findings. You NEVER modify files.
+
+## How to Audit
+
+1. **Run the opsward diagnostic** via Bash:
+   ```
+   opsward diagnose . --format json
+   ```
+   If `opsward` is not installed, fall back to manual inspection (steps below).
+
+2. **Run maintenance checks** via Bash:
+   ```
+   opsward maintain . --format json
+   ```
+
+3. **Interpret and present** the combined results as a report card.
+
+## Fallback: Manual Inspection
+
+If `opsward` is not available, check these manually:
+
+1. **CLAUDE.md quality** — Is it concise, actionable, and current?
+2. **Documentation** — Do `misc/docs/docs_guide.md` and core docs exist and have real content?
+3. **Skills** — Do `.claude/skills/` entries have valid SKILL.md files with descriptions?
+4. **Rules** — Are `.claude/rules/` entries specific and actionable?
+5. **Cross-references** — Do paths mentioned in CLAUDE.md actually exist?
+
+## How to Report
+
+Summarize findings as a bulleted list with scores (0-100) per category and specific suggestions for improvement. Be constructive and specific.

denote-0.0.2/.claude/skills/opsward/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: opsward
+description: Run opsward to assess and improve this project's AI agent setup. Use when the user says 'opsward', 'check my setup', 'improve my AI config', or wants a full audit and remediation.
+---
+
+# Opsward — AI Setup Manager
+
+Assess this project's AI agent setup and guide improvements. Combines opsward's deterministic CLI tools with your ability to read code, reason about quality, and make intelligent edits.
+
+## Prerequisites
+
+Requires `opsward` to be installed (`pip install opsward`). If the command is not found, tell the user to install it.
+
+## Workflow
+
+### 1. Diagnose
+
+Run the deterministic diagnostic:
+
+```bash
+opsward diagnose . --format json
+```
+
+```bash
+opsward diagnose .
+```
+
+### 2. Interpret and decide
+
+Based on the grade, decide the next step:
+- **Grade F or D** (score < 70): The project is missing core artifacts. Focus on generation — scaffold CLAUDE.md, docs, skills.
+- **Grade C or B** (score 70-89): The structure exists but has drift or gaps. Focus on maintenance — fix stale references, flesh out empty docs.
+- **Grade A** (score 90+): Setup is healthy. Offer targeted fine-tuning — improve the lowest-scoring dimensions.
+
+### 3. Go beyond the scores
+
+Opsward's scores are heuristic (regex-based). You can assess semantic quality that opsward can't:
+- Is the CLAUDE.md actually accurate for this project?
+- Do the docs contain real content or just template stubs?
+- Are the commands correct and up-to-date?
+
+Read source files, configs, and existing docs to form your own assessment. Use Read, Grep, Glob, and Bash freely — these are read-only and safe.
+
+### 4. Execute the appropriate workflow
+
+- **Generation**: Run `opsward generate .` to preview, then `opsward generate . --write` to create scaffolds. Then read the project's actual code and customize each generated file with real content.
+- **Maintenance**: Run `opsward maintain . --format json` to get structural issues. Also check for semantic drift (docs that no longer match the code). Fix issues using Edit/Write.
+- **Fine-tuning**: Read the lowest-scoring component, identify specific improvements, and apply them.
+
+Always ask the user before writing or editing files.
+
+### 5. Re-diagnose
+
+After making changes, run `opsward diagnose .` again. Show before/after scores and summarize what was done.
+
+## Permissions
+
+This skill uses Claude Code's standard permission model:
+- **Read-only operations** (Read, Glob, Grep, Bash for inspection): always safe, used freely
+- **Write operations** (Write, Edit): Claude Code prompts the user per their permission settings
+- **Destructive operations** (deleting files, removing content): always ask for explicit confirmation
+
+The skill never assumes elevated permissions. If the user wants faster workflows, they can configure auto-allow in their Claude Code settings — but this is their choice.

denote-0.0.2/.claude/skills/opsward-diagnose/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: opsward-diagnose
+description: Diagnose the health of this project's AI agent setup. Use when the user asks to check, audit, or score the project's CLAUDE.md, skills, docs, or agent configuration.
+---
+
+# Diagnose AI Setup
+
+Run opsward's deterministic diagnostic, then go deeper with your own analysis, and offer fixes.
+
+## Prerequisites
+
+Requires `opsward` to be installed (`pip install opsward`). If the command is not found, tell the user to install it.
+
+## Workflow
+
+### 1. Run the deterministic diagnostic
+
+```bash
+opsward diagnose . --format json
+```
+
+This returns structured scores (0-100) for CLAUDE.md quality, documentation, skills, setup, and cross-references. Also run the text version for the user:
+
+```bash
+opsward diagnose .
+```
+
+### 2. Go deeper than the scores
+
+Opsward uses regex heuristics — it catches structural issues but can't assess semantic quality. You can. For each component:
+
+- **CLAUDE.md**: Read it. Is the module map accurate? Are the commands actually correct? Does it match the real project structure? Check `pyproject.toml`, `package.json`, source directories.
+- **Docs**: Read each doc. Is the content real or just a template stub? Does `architecture.md` describe the actual architecture?
+- **Skills**: Read each SKILL.md. Are the trigger descriptions clear? Do the instructions make sense for this project?
+- **Cross-references**: Opsward checks path existence. You can check whether referenced files have the content the reference implies.
+
+Use Read, Glob, and Grep freely to inspect the project — these are read-only and safe.
+
+### 3. Present findings
+
+For each component:
+- State the opsward score and what it measures
+- Add your own observations (what opsward can't catch)
+- Highlight the most impactful improvements
+
+### 4. Offer fixes
+
+For each issue, propose a concrete fix:
+- Missing CLAUDE.md → offer to generate or write a tailored one
+- Inaccurate module map → read the actual directory structure and rewrite it
+- Low commands score → read `pyproject.toml`/`package.json` and add real commands
+- Broken cross-references → identify stale paths, update or remove them
+- Missing/empty docs → read the codebase and write real content (not just templates)
+- Missing skill descriptions → read the skill directory and write a proper description
+
+### 5. Apply fixes with user approval
+
+Always ask before writing or editing files. Show the proposed change first.
+
+### 6. Re-run diagnostic
+
+```bash
+opsward diagnose .
+```
+
+Show before/after scores.
+
+## Scoring Dimensions (for reference)
+
+- **CLAUDE.md quality** (35% weight): commands/workflows, architecture clarity, conventions, conciseness, currency, actionability
+- **Documentation** (25%): docs_guide.md, core docs, content, cross-refs
+- **Skills** (20%): SKILL.md presence, descriptions
+- **Setup** (10%): rules, agents, hooks configuration
+- **Cross-references** (10%): paths in CLAUDE.md that actually exist on disk
+
+## Permissions
+
+This skill needs no special permissions for diagnosis (read-only). Applying fixes requires write permission — Claude Code will prompt the user for approval on each write/edit action as configured in their permission settings.

denote-0.0.2/.claude/skills/opsward-generate/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: opsward-generate
+description: Generate missing AI setup artifacts for this project. Use when the user asks to scaffold, create, or bootstrap CLAUDE.md, docs, skills, or agent configuration.
+---
+
+# Generate AI Setup Artifacts
+
+Use opsward to scaffold missing artifacts, then go beyond templates — read the actual codebase and fill in real content.
+
+## Prerequisites
+
+Requires `opsward` to be installed (`pip install opsward`). If the command is not found, tell the user to install it.
+
+## Workflow
+
+### 1. Preview what would be generated
+
+```bash
+opsward generate .
+```
+
+This shows a dry-run list of files that would be created. Existing files are never overwritten.
+
+### 2. Present the plan
+
+For each proposed file:
+- Explain what it is and why it's useful
+- Note if it's a core artifact (CLAUDE.md, docs_guide) vs optional (roadmap, glossary)
+- Let the user decide which files to create
+
+### 3. Generate the scaffolds
+
+```bash
+opsward generate . --write
+```
+
+### 4. Replace templates with real content
+
+This is the critical step. Opsward generates templates with placeholders — you turn them into useful documents by reading the actual project:
+
+- **CLAUDE.md**: Read `pyproject.toml`/`package.json` for real project name and description. Scan source directories to build an accurate module map with real descriptions. Extract actual build/test/lint commands from config files. Check for linter/formatter configs and document real conventions.
+- **architecture.md**: Read the source code to understand the real architecture. Document actual data flow, module responsibilities, and key abstractions.
+- **conventions.md**: Look at existing code patterns — naming, error handling, import style — and document what you find.
+- **docs_guide.md**: Verify it accurately indexes the docs that were created.
+- **testing.md**: Read test files to document actual test patterns, fixtures, and how to run tests.
+
+Use Read, Glob, Grep, and Bash freely to understand the project before writing.
+
+### 5. Verify the result
+
+```bash
+opsward diagnose .
+```
+
+Show the resulting score. If any component scores low, offer to improve it further.
+
+## Permissions
+
+- **Read access**: Used freely to inspect the project (always safe).
+- **Write access**: Needed to create new files. Claude Code prompts for approval per the user's permission settings.
+- **Bash**: Used to run opsward commands and inspect the project (e.g., `git log`, `tree`).
+
+If the user wants to skip confirmation prompts for file creation, they can configure auto-allow for Write in their Claude Code settings — but this is their choice, not something the skill assumes.

denote-0.0.2/.claude/skills/opsward-maintain/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: opsward-maintain
+description: Check documentation and AI setup for staleness, drift, or inconsistency. Use when the user asks to maintain, refresh, or update project docs and AI configuration.
+---
+
+# Maintain AI Setup
+
+Run opsward's maintenance checks, go deeper with your own analysis, then fix issues found.
+
+## Prerequisites
+
+Requires `opsward` to be installed (`pip install opsward`). If the command is not found, tell the user to install it.
+
+## Workflow
+
+### 1. Run maintenance checks
+
+```bash
+opsward maintain . --format json
+```
+
+This returns issues categorized as: stale_path, sync_issue, outdated_doc, incomplete_skill, empty_doc. Also run the text version:
+
+```bash
+opsward maintain .
+```
+
+### 2. Go deeper than opsward
+
+Opsward catches structural drift (broken paths, unlisted docs, empty stubs). You can catch semantic drift:
+
+- **Accuracy**: Read docs and compare against the actual code. Does `architecture.md` still describe the real architecture? Has the module map in CLAUDE.md drifted from the actual directory structure?
+- **Completeness**: Are there new modules, commands, or patterns not yet documented? Check `git log` for recent changes to source files that docs reference.
+- **Obsolescence**: Do docs reference removed features, old API signatures, or deprecated patterns?
+- **Consistency**: Do different docs contradict each other? Does CLAUDE.md say one thing while conventions.md says another?
+
+Use Read, Grep, Glob, and Bash (`git log`, `git diff`) freely for this analysis.
+
+### 3. Categorize and prioritize
+
+Group all issues (opsward's + yours) by severity:
+- **High priority**: Incorrect information (wrong commands, inaccurate architecture), broken references that mislead
+- **Medium priority**: Outdated docs, incomplete descriptions, missing new content
+- **Low priority**: Empty stubs, minor formatting, cosmetic issues
+
+### 4. Propose and apply fixes
+
+For each issue, propose a concrete fix:
+- **Stale path**: Determine if the file was renamed, moved, or deleted. Update or remove the reference.
+- **Inaccurate doc**: Read the source code and rewrite the relevant section with correct information.
+- **Sync issue**: Add missing docs to docs_guide.md, or remove references to deleted docs.
+- **Outdated doc**: Read the code it describes, update to reflect current state.
+- **Incomplete skill**: Read the skill directory, write a proper SKILL.md with description.
+- **Empty doc**: Read the project to understand what should go in it, write real content.
+
+Always ask the user before writing or editing. Show proposed changes first. For destructive operations (removing content, deleting files), explain why and get explicit confirmation.
+
+### 5. Verify
+
+```bash
+opsward maintain .
+opsward diagnose .
+```
+
+Show that issues are resolved and the overall score improved.
+
+## Permissions
+
+- **Read/Grep/Glob**: Used freely for analysis (always safe).
+- **Edit**: Needed to fix existing files. Claude Code prompts per user settings.
+- **Write**: Needed for new files. Claude Code prompts per user settings.
+- **Bash**: For opsward commands and git inspection. Claude Code prompts per user settings.
+
+This skill never deletes files without explicit user confirmation, even if the user has auto-allow enabled for other operations.

denote-0.0.2/.gitattributes

@@ -0,0 +1 @@
+*.ipynb linguist-documentation

denote-0.0.2/.github/workflows/ci.yml

@@ -0,0 +1,259 @@
+name: Continuous Integration (uv)
+on: [push, pull_request]
+
+# Note: Environment variables (PROJECT_NAME and vars from [tool.wads.ci.env])
+# are set by the read-ci-config action in the setup job and made available
+# to all subsequent jobs via GITHUB_ENV
+
+jobs:
+  # First job: Read configuration from pyproject.toml
+  setup:
+    name: Read Configuration
+    runs-on: ubuntu-latest
+    outputs:
+      project-name: ${{ steps.config.outputs.project-name }}
+      python-versions: ${{ steps.config.outputs.python-versions }}
+      pytest-args: ${{ steps.config.outputs.pytest-args }}
+      coverage-enabled: ${{ steps.config.outputs.coverage-enabled }}
+      exclude-paths: ${{ steps.config.outputs.exclude-paths }}
+      test-on-windows: ${{ steps.config.outputs.test-on-windows }}
+      build-sdist: ${{ steps.config.outputs.build-sdist }}
+      build-wheel: ${{ steps.config.outputs.build-wheel }}
+      metrics-enabled: ${{ steps.config.outputs.metrics-enabled }}
+      metrics-config-path: ${{ steps.config.outputs.metrics-config-path }}
+      metrics-storage-branch: ${{ steps.config.outputs.metrics-storage-branch }}
+      metrics-python-version: ${{ steps.config.outputs.metrics-python-version }}
+      metrics-force-run: ${{ steps.config.outputs.metrics-force-run }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Read CI Config
+        id: config
+        uses: i2mint/wads/actions/read-ci-config@master
+        with:
+          pyproject-path: .
+
+  # Second job: Validation using the config
+  validation:
+    name: Validation
+    if: "!contains(github.event.head_commit.message, '[skip ci]')"
+    needs: setup
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ${{ fromJson(needs.setup.outputs.python-versions) }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install System Dependencies
+        uses: i2mint/wads/actions/install-system-deps@master
+        with:
+          pyproject-path: .
+
+      - name: Create virtual environment
+        run: uv venv .venv
+
+      - name: Install Dependencies
+        run: |
+          source .venv/bin/activate
+          uv pip install -e ".[dev,test]"
+
+      - name: Format Source Code
+        run: uvx ruff format .
+
+      - name: Lint Validation
+        run: uvx ruff check --output-format=github ${{ needs.setup.outputs.project-name }}
+
+      - name: Run Tests
+        run: |
+          source .venv/bin/activate
+          PYTEST_ARGS="${{ needs.setup.outputs.pytest-args }}"
+          EXCLUDE="${{ needs.setup.outputs.exclude-paths }}"
+          COVERAGE="${{ needs.setup.outputs.coverage-enabled }}"
+          ROOT_DIR="${{ needs.setup.outputs.project-name }}"
+
+          CMD="python -m pytest"
+
+          # Add coverage flags
+          if [ "$COVERAGE" = "true" ]; then
+            uv pip install pytest-cov
+            CMD="$CMD --cov=$ROOT_DIR --cov-report=term-missing"
+          fi
+
+          # Skip doctest-modules (backends require optional deps + audio fixtures)
+          # CMD="$CMD --doctest-modules"
+          # CMD="$CMD -o doctest_optionflags='ELLIPSIS IGNORE_EXCEPTION_DETAIL'"
+
+          # Add exclude paths
+          if [ -n "$EXCLUDE" ]; then
+            IFS=',' read -ra PATHS <<< "$EXCLUDE"
+            for path in "${PATHS[@]}"; do
+              path=$(echo "$path" | xargs)
+              CMD="$CMD --ignore=$path"
+            done
+          fi
+
+          # Add extra pytest args
+          if [ -n "$PYTEST_ARGS" ]; then
+            CMD="$CMD $PYTEST_ARGS"
+          fi
+
+          # Add test directories (both tests/ and source for doctests)
+          CMD="$CMD tests/"
+
+          echo "Running: $CMD"
+          eval $CMD
+
+      - name: Track Code Metrics
+        if: needs.setup.outputs.metrics-enabled == 'true'
+        uses: i2mint/umpyre/actions/track-metrics@master
+        continue-on-error: true
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          config-path: ${{ needs.setup.outputs.metrics-config-path }}
+          storage-branch: ${{ needs.setup.outputs.metrics-storage-branch }}
+          python-version: ${{ needs.setup.outputs.metrics-python-version }}
+          force-run: ${{ needs.setup.outputs.metrics-force-run }}
+
+  # Optional Windows testing (if enabled in config)
+  windows-validation:
+    name: Windows Tests
+    if: "!contains(github.event.head_commit.message, '[skip ci]') && needs.setup.outputs.test-on-windows == 'true'"
+    needs: setup
+    runs-on: windows-latest
+    continue-on-error: true
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install ${{ fromJson(needs.setup.outputs.python-versions)[0] }}
+
+      - name: Install System Dependencies
+        uses: i2mint/wads/actions/install-system-deps@master
+        with:
+          pyproject-path: .
+
+      - name: Create virtual environment
+        run: uv venv .venv
+
+      - name: Install Dependencies
+        run: |
+          .venv\Scripts\activate
+          uv pip install -e ".[dev,test]"
+
+      - name: Run tests
+        id: test
+        continue-on-error: true
+        run: pytest
+
+      - name: Report test results
+        if: always()
+        run: |
+          if ("${{ steps.test.outcome }}" -eq "failure") {
+            echo "::warning::Windows tests failed but workflow continues"
+            echo "## ⚠️ Windows Tests Failed" >> $env:GITHUB_STEP_SUMMARY
+            echo "Tests failed on Windows but this is informational only." >> $env:GITHUB_STEP_SUMMARY
+          } else {
+            echo "## ✅ Windows Tests Passed" >> $env:GITHUB_STEP_SUMMARY
+          }
+
+  # Publishing job
+  publish:
+    name: Publish
+    permissions:
+      contents: write
+    if: "!contains(github.event.head_commit.message, '[skip ci]') && (github.ref == 'refs/heads/master' || github.ref == 'refs/heads/main')"
+    needs: [setup, validation]
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install ${{ fromJson(needs.setup.outputs.python-versions)[0] }}
+
+      - name: Format Source Code
+        run: uvx ruff format .
+
+      - name: Update Version Number
+        id: version
+        uses: i2mint/isee/actions/bump-version-number@master
+
+      - name: Build Distribution
+        run: |
+          BUILD_ARGS=""
+          if [ "${{ needs.setup.outputs.build-sdist }}" = "false" ]; then
+            BUILD_ARGS="$BUILD_ARGS --no-sdist"
+          fi
+          if [ "${{ needs.setup.outputs.build-wheel }}" = "false" ]; then
+            BUILD_ARGS="$BUILD_ARGS --no-wheel"
+          fi
+          uv build $BUILD_ARGS
+
+      - name: Publish to PyPI
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_PASSWORD }}
+        run: uv publish dist/*
+
+      - name: Force SSH for git remote
+        run: |
+          git remote set-url origin git@github.com:${{ github.repository }}.git
+
+      - name: Commit Changes
+        uses: i2mint/wads/actions/git-commit@master
+        with:
+          commit-message: "**CI** Formatted code + Updated version to ${{ env.VERSION }} [skip ci]"
+          ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
+          push: true
+
+      - name: Tag Repository
+        uses: i2mint/wads/actions/git-tag@master
+        with:
+          tag: ${{ env.VERSION }}
+          message: "Release version ${{ env.VERSION }}"
+          push: true
+
+  # Optional GitHub Pages
+  github-pages:
+    name: Publish GitHub Pages
+    permissions:
+      contents: write
+      pages: write
+      id-token: write
+    if: "!contains(github.event.head_commit.message, '[skip ci]') && github.ref == format('refs/heads/{0}', github.event.repository.default_branch)"
+    needs: publish
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: i2mint/epythet/actions/publish-github-pages@master
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          ignore: "tests/,scrap/,examples/"

denote-0.0.2/.gitignore

@@ -0,0 +1,121 @@
+wads_configs.json
+data/wads_configs.json
+wads/data/wads_configs.json
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+
+.DS_Store
+# C extensions
+*.so
+
+# TLS certificates
+## Ignore all PEM files anywhere
+*.pem
+## Also ignore any certs directory
+certs/
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+_build
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+docs/*
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# PyCharm
+.idea