noetrail 0.10.0a1__tar.gz

noetrail-0.10.0a1/.github/CODEOWNERS

@@ -0,0 +1,33 @@
+# Review ownership. Noetrail has one maintainer, so a single catch-all rule
+# would be enough; the paths below are listed separately because they are the
+# ones where an unreviewed change is expensive, and because this file should
+# still say something useful when there is more than one owner.
+#
+# CODEOWNERS only requests reviews. Requiring them is a branch-protection
+# setting on `main`, which is configured in the repository settings, not here.
+
+*                                   @patsch1
+
+# On-disk format, migrations, and the code that decides what a path may be.
+/src/noetrail/migrations.py         @patsch1
+/src/noetrail/layout.py             @patsch1
+/src/noetrail/schema.py             @patsch1
+/.knowledge/                        @patsch1
+
+# Agent-facing boundaries: the MCP surface and the isolated fetcher.
+/src/noetrail/mcp.py                @patsch1
+/src/noetrail/mcp_protocol.py       @patsch1
+/src/noetrail/bookmark_fetcher.py   @patsch1
+
+# Supply chain and publication: workflows, packaging metadata, and the
+# scripts a release is checked with.
+/.github/                           @patsch1
+/pyproject.toml                     @patsch1
+/MANIFEST.in                        @patsch1
+/tools/                             @patsch1
+
+# Governance and security promises.
+/SECURITY.md                        @patsch1
+/CODE_OF_CONDUCT.md                 @patsch1
+/CONTRIBUTING.md                    @patsch1
+/LICENSE                            @patsch1

noetrail-0.10.0a1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,96 @@
+name: Bug report
+description: Something behaves differently than documented, or fails.
+title: "bug: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        SUPPORT.md asks for the environment and a `noetrail doctor` report with
+        every issue. This form requires it, because a bug report without it
+        usually costs one round trip before anything can be looked at.
+
+        Use synthetic data. Never paste a real vault entry, export,
+        attachment, URL with personal content, token, or infrastructure
+        detail. Redact absolute paths that contain names.
+  - type: checkboxes
+    id: preflight
+    attributes:
+      label: Before reporting
+      options:
+        - label: I searched the existing open and closed issues.
+          required: true
+        - label: I can reproduce this with synthetic data in a temporary vault, or I explain below why not.
+          required: true
+        - label: This report contains no personal vault content, credentials, or private infrastructure details.
+          required: true
+        - label: This is not a security vulnerability. Those go to the private channel in SECURITY.md.
+          required: true
+  - type: input
+    id: version
+    attributes:
+      label: Noetrail version
+      description: Output of `noetrail --version`.
+      placeholder: "noetrail 0.10.0a1"
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      description: Output of `python3 -V`.
+      placeholder: "Python 3.13.2"
+    validations:
+      required: true
+  - type: input
+    id: os
+    attributes:
+      label: Operating system
+      description: Name and version, plus the filesystem if the vault is not on local storage.
+      placeholder: "Debian 13, ext4"
+    validations:
+      required: true
+  - type: dropdown
+    id: surface
+    attributes:
+      label: Command surface
+      options:
+        - CLI
+        - Noetrail MCP
+        - bookmark fetcher
+        - both CLI and MCP
+    validations:
+      required: true
+  - type: textarea
+    id: doctor
+    attributes:
+      label: "`noetrail doctor` output"
+      description: Run `noetrail doctor` against the affected instance and paste the JSON report unchanged, except for paths you need to redact.
+      render: json
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to reproduce
+      description: The exact commands, in order, starting from a state a reader can create.
+      placeholder: |
+        1. noetrail --data-root "$T/data" --config-root "$T/config" init
+        2. noetrail ... capture --type thought --title "synthetic" --text "synthetic"
+        3. noetrail ... search synthetic
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected and actual result
+      description: What you expected, what happened, and the sanitized error or exit code.
+    validations:
+      required: true
+  - type: textarea
+    id: context
+    attributes:
+      label: Anything else
+      description: Schema packs in use, vault size, MCP client, container deployment. Optional.
+    validations:
+      required: false

noetrail-0.10.0a1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,15 @@
+# Blank issues are disabled on purpose: the three forms exist so that a report
+# arrives with the version, the interpreter, the operating system, and a
+# `noetrail doctor` report already in it, which SUPPORT.md asks for and a free
+# text box does not enforce.
+blank_issues_enabled: false
+contact_links:
+  - name: Question or idea
+    url: https://github.com/patsch1/noetrail/discussions
+    about: Usage questions, agent setups, and open-ended ideas belong in Discussions, not in the issue tracker.
+  - name: Report a security vulnerability
+    url: https://github.com/patsch1/noetrail/security/advisories/new
+    about: Never file a vulnerability as a public issue. Use the private advisory form; SECURITY.md states the response times.
+  - name: Support and what to include
+    url: https://github.com/patsch1/noetrail/blob/main/SUPPORT.md
+    about: What this project does and does not support, and how to sanitize a report before sending it.

noetrail-0.10.0a1/.github/ISSUE_TEMPLATE/documentation.yml

@@ -0,0 +1,75 @@
+name: Documentation problem
+description: A documented step is wrong, missing, unclear, or out of date.
+title: "docs: "
+labels: ["documentation"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        The shell blocks in `README.md` and `docs/quickstart.md` are executed
+        by the test suite, so a failing block there is a real defect. Blocks in
+        other documents are not, and a report is the only way they get fixed.
+
+        Redact absolute paths that contain personal names.
+  - type: checkboxes
+    id: preflight
+    attributes:
+      label: Before reporting
+      options:
+        - label: I searched the existing open and closed issues.
+          required: true
+        - label: This report contains no personal vault content or credentials.
+          required: true
+  - type: input
+    id: document
+    attributes:
+      label: Document
+      description: Repository path, and the heading or line if you have it.
+      placeholder: "docs/quickstart.md, section 'Import Markdown'"
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Noetrail version
+      description: Output of `noetrail --version`. Documentation is versioned with the program.
+      placeholder: "noetrail 0.10.0a1"
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      description: Output of `python3 -V`.
+      placeholder: "Python 3.13.2"
+    validations:
+      required: true
+  - type: input
+    id: os
+    attributes:
+      label: Operating system
+      placeholder: "Ubuntu 24.04"
+    validations:
+      required: true
+  - type: textarea
+    id: doctor
+    attributes:
+      label: "`noetrail doctor` output"
+      description: Most documentation problems are really a mismatch between the documented layout and the actual one. This report shows which it is.
+      render: json
+    validations:
+      required: true
+  - type: textarea
+    id: problem
+    attributes:
+      label: What is wrong
+      description: Quote the documented text, then say what actually happens or what is missing. Include the command and its sanitized output if a documented step failed.
+    validations:
+      required: true
+  - type: textarea
+    id: suggestion
+    attributes:
+      label: Suggested wording
+      description: Optional. A concrete replacement is usually faster than a discussion.
+    validations:
+      required: false

noetrail-0.10.0a1/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,77 @@
+name: Feature request
+description: Propose a bounded change in behavior.
+title: "feature: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Noetrail is a one-person project before `1.0`. A proposal that names
+        the problem, the smallest change that solves it, and what it would
+        cost has a much better chance than a list of wishes.
+
+        ROADMAP.md lists what is planned and what is deliberately out of
+        scope. Please check it first.
+  - type: checkboxes
+    id: preflight
+    attributes:
+      label: Before proposing
+      options:
+        - label: I searched the existing open and closed issues.
+          required: true
+        - label: I read ROADMAP.md and this is not already listed as a non-goal.
+          required: true
+        - label: This request contains no personal vault content or credentials.
+          required: true
+  - type: input
+    id: version
+    attributes:
+      label: Noetrail version
+      description: Output of `noetrail --version`, so the proposal is read against the right behavior.
+      placeholder: "noetrail 0.10.0a1"
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      description: Output of `python3 -V`.
+      placeholder: "Python 3.13.2"
+    validations:
+      required: true
+  - type: input
+    id: os
+    attributes:
+      label: Operating system
+      placeholder: "macOS 15.3"
+    validations:
+      required: true
+  - type: textarea
+    id: doctor
+    attributes:
+      label: "`noetrail doctor` output"
+      description: The report from the instance the proposal is about. It shows the schema version, the loaded packs, and the layout the request has to fit.
+      render: json
+    validations:
+      required: true
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What you are trying to do today, and where the current commands or MCP tools stop you. Describe the situation, not the solution.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed change
+      description: The smallest change that would solve it. Name the affected surface — CLI, MCP, schema packs, on-disk format, documentation.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives and impact
+      description: What you considered instead, and what this would cost — a data-format change, a migration, a new dependency, a wider agent permission. Say so if you do not know.
+    validations:
+      required: true

noetrail-0.10.0a1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,47 @@
+<!--
+The four sections below are the four things CONTRIBUTING.md asks a pull
+request to describe. Keep one coherent change per pull request.
+Delete a section only if you replace it with a sentence saying why it does not
+apply.
+-->
+
+## Summary
+
+<!-- What changes, and why. One paragraph. -->
+
+## User-visible behavior and compatibility
+
+<!--
+Which command, MCP tool, output field, or file layout changes, and what an
+existing installation notices. Write "none" if nothing user-visible changes.
+-->
+
+## Security and privacy boundaries
+
+<!--
+Which boundary this touches: the Git/private-data separation, the narrow MCP
+surface, the isolated bookmark fetcher, attachment ingestion, purge, secrets.
+Write "none affected" if it touches none of them.
+-->
+
+## Tests run
+
+<!--
+Paste the commands you ran and their result. `make check` covers all six
+gates; name the individual gates if you ran them separately.
+-->
+
+## Migration, rollback, and documentation
+
+<!--
+On-disk format changes need an ordered, deterministic, dry-run migration and a
+rollback path. Name the documents you updated, or say why none needed it.
+-->
+
+---
+
+- [ ] `make check` passes locally (lint, types, tests, coverage, secrets, boundary).
+- [ ] Tests and fixtures use synthetic data only — no real vault, export, attachment, URL, or credential.
+- [ ] Documentation, `CHANGELOG.md`, and any affected `docs/` page are updated.
+- [ ] No generated wheels, private runtime directories, or copied logs are included.
+- [ ] I am submitting this under the [Apache License 2.0](../LICENSE), per section 5 of that license.

noetrail-0.10.0a1/.github/dependabot.yml

@@ -0,0 +1,19 @@
+version: 2
+
+updates:
+  # The workflows pin actions to a commit SHA, which is safe but frozen:
+  # without this, a pinned action would keep running its original code
+  # indefinitely, security fixes included. Dependabot rewrites the SHA and the
+  # trailing version comment together.
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "ci"
+    labels:
+      - "dependencies"
+      - "github-actions"
+
+# There is deliberately no "pip" entry: the runtime has no third-party
+# dependencies, and the two CI-only tools are pinned in the workflows.

noetrail-0.10.0a1/.github/workflows/ci.yml

@@ -0,0 +1,153 @@
+name: CI
+
+# An unfiltered `push` plus `pull_request` ran every job twice for any branch
+# that had an open pull request. Pushes are now limited to the branch and the
+# tags that are worth a run on their own; everything else arrives via the
+# pull-request event.
+on:
+  push:
+    branches: [main]
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+      - "v[0-9]+.[0-9]+.[0-9]+a[0-9]+"
+      - "v[0-9]+.[0-9]+.[0-9]+b[0-9]+"
+      - "v[0-9]+.[0-9]+.[0-9]+rc[0-9]+"
+  pull_request:
+
+# Only the newest commit of a ref is interesting; superseded runs are cancelled
+# instead of competing for runners.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+# Third-party actions are pinned to a commit SHA. A mutable major tag can be
+# repointed at new code without any change in this repository, so the version
+# in the trailing comment is documentation only.
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.13"
+      - name: Install linter
+        run: python -m pip install ruff==0.14.0
+      - name: Check style and common defects
+        run: python -m ruff check .
+
+  typecheck:
+    name: Type check
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          # The lowest supported interpreter: mypy resolves version-conditional
+          # standard-library stubs against the running Python, so checking on
+          # 3.13 would not see what 3.11 users get.
+          python-version: "3.11"
+      - name: Install type checker
+        run: python -m pip install mypy==1.20.2
+      # Scope, strictness and per-module overrides live in pyproject.toml.
+      - name: Check types
+        run: python -m mypy
+
+  test:
+    name: Python ${{ matrix.python-version }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+        # One macOS job, not a second full matrix. Its purpose is the platform,
+        # not the interpreter: `/var` is a symlink there and `/tmp` on Linux is
+        # not, which is a difference the suite has already been wrong about.
+        # A macOS runner also bills at ten times a Linux one on a private
+        # repository, so the coverage is bought at one job, on the version the
+        # other gates use.
+        include:
+          - os: macos-latest
+            python-version: "3.13"
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Run synthetic tests
+        run: python -m unittest discover -s tests -t . -v
+      - name: Check repository for secrets
+        run: python tools/check_secrets.py
+      - name: Check Git and private-data boundary
+        run: python tools/check_git_boundary.py
+      - name: Build wheel
+        run: python -m pip wheel . --wheel-dir "${RUNNER_TEMP}/wheel"
+
+  coverage:
+    name: Coverage
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.13"
+      # `tools/coverage.py` is dependency-free and traces the child processes
+      # the suite starts, which is most of it. Thresholds live in that file and
+      # a shortfall fails this job.
+      - name: Measure statement coverage
+        run: python tools/coverage.py --json "${RUNNER_TEMP}/coverage.json"
+
+  sdist:
+    name: Source-distribution acceptance
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.13"
+      - name: Install build frontend
+        run: python -m pip install build==1.5.1
+      - name: Build source distribution
+        run: python -m build --sdist --outdir dist
+      # The sdist is the artifact a distribution packager rebuilds and tests
+      # from. Running the suite inside the unpacked archive is the only check
+      # that catches a file MANIFEST.in forgot -- `tests/__init__.py` was
+      # missing once, and nothing outside this job noticed.
+      - name: Run the suite from the unpacked source distribution
+        run: |
+          mkdir -p "${RUNNER_TEMP}/sdist"
+          tar xzf dist/noetrail-*.tar.gz -C "${RUNNER_TEMP}/sdist"
+          cd "${RUNNER_TEMP}/sdist"/noetrail-*/
+          python -m unittest discover -s tests -t . -v
+
+  installed-wheel:
+    name: Installed-wheel acceptance
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.13"
+      - name: Build wheel
+        run: python -m pip wheel . --no-deps --wheel-dir dist
+      - name: Install and exercise the wheel
+        run: |
+          python tools/release_acceptance.py \
+            --wheel "$(find dist -name 'noetrail-*.whl' -print -quit)"

noetrail-0.10.0a1/.github/workflows/codeql.yml

@@ -0,0 +1,53 @@
+name: CodeQL
+
+# Static analysis on the Python sources. Runs on the same events as CI plus a
+# weekly schedule, because CodeQL queries are updated independently of this
+# repository and a finding can appear without any commit here.
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "17 5 * * 1"
+
+concurrency:
+  group: codeql-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+# Third-party actions are pinned to a commit SHA. A mutable major tag can be
+# repointed at new code without any change in this repository, so the version
+# in the trailing comment is documentation only.
+jobs:
+  analyze:
+    name: Analyze Python
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    # Code scanning needs GitHub Advanced Security on a private repository; on
+    # a personal plan CodeQL is only free for public ones. Without it the job
+    # fails during init with a permissions error rather than a finding, which
+    # is noise on every pull request and would block a required check for a
+    # reason that has nothing to do with the code. Skipping while private
+    # keeps the workflow honest: it starts analysing by itself the moment the
+    # repository is published, with no change here.
+    if: github.event.repository.private == false
+    permissions:
+      # Writing the results into the repository's code-scanning view is the
+      # only extra permission this job needs.
+      security-events: write
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
+        with:
+          languages: python
+          build-mode: none
+          queries: security-and-quality
+      - name: Perform CodeQL analysis
+        uses: github/codeql-action/analyze@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
+        with:
+          category: "/language:python"

noetrail-0.10.0a1/.github/workflows/deploy-zeroclaw.yml

@@ -0,0 +1,49 @@
+name: Publish ZeroClaw candidate
+
+on:
+  workflow_run:
+    workflows: [CI]
+    types: [completed]
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: zeroclaw-candidate
+  cancel-in-progress: false
+
+jobs:
+  candidate:
+    if: >-
+      github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.event == 'push' &&
+      github.event.workflow_run.head_branch == 'main' &&
+      github.event.workflow_run.head_repository.full_name == github.repository
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.event.workflow_run.head_sha }}
+          fetch-depth: 1
+      - name: Publish the tested main commit
+        env:
+          CANDIDATE_SHA: ${{ github.event.workflow_run.head_sha }}
+        run: |
+          set -euo pipefail
+          git fetch origin main
+          if [ "$(git rev-parse origin/main)" != "$CANDIDATE_SHA" ]; then
+            echo "A newer main commit exists; skip this candidate."
+            exit 0
+          fi
+          python3 tools/zeroclaw_candidate.py "$CANDIDATE_SHA" deploy/zeroclaw/candidate
+          git config user.name github-actions\[bot\]
+          git config user.email 41898282+github-actions\[bot\]@users.noreply.github.com
+          git add deploy/zeroclaw/candidate
+          git commit -m "ci: publish candidate $CANDIDATE_SHA"
+          # Only this generated branch is replaced; main remains PR-protected.
+          # Concurrency serializes publishers, and the main check rejects stale CI.
+          git push --force origin HEAD:refs/heads/deploy/test