joplin-md-sync 1.5.5__tar.gz

joplin_md_sync-1.5.5/.version

@@ -0,0 +1 @@
+1.5.5

joplin_md_sync-1.5.5/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 joplin-md-sync contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

joplin_md_sync-1.5.5/MANIFEST.in

@@ -0,0 +1,10 @@
+include .version
+recursive-include docs *.md
+recursive-include examples *.json *.md *.ps1 *.py
+include examples/agent-notes-repository/.gitignore
+include scripts/prepare_chatgpt_action.py
+include scripts/joplin_terminal_service/collect_joplin_debug.sh
+include scripts/joplin_terminal_service/install_joplin_terminal.py
+include scripts/joplin_terminal_service/joplin_terminal_common.py
+include scripts/joplin_terminal_service/run_joplin_terminal.py
+recursive-include scripts/joplin_terminal_service/systemd *.service

joplin_md_sync-1.5.5/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: joplin-md-sync
+Version: 1.5.5
+Summary: Safe two-way synchronization between Joplin notes and a local Markdown workspace, built for autonomous coding agents
+Author: joplin-md-sync contributors
+License-Expression: MIT
+Project-URL: Homepage, https://joplin-mcp.romancello.net/
+Project-URL: Documentation, https://joplin-mcp.romancello.net/
+Project-URL: Repository, https://github.com/kogeler/joplin-md-sync
+Project-URL: Issues, https://github.com/kogeler/joplin-md-sync/issues
+Project-URL: Changelog, https://github.com/kogeler/joplin-md-sync/blob/main/CHANGELOG.md
+Keywords: joplin,markdown,sync,notes,cli,agents
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Utilities
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: bandit[toml]==1.9.4; extra == "dev"
+Requires-Dist: mypy==2.3.1; extra == "dev"
+Requires-Dist: pip-audit==2.10.1; extra == "dev"
+Requires-Dist: ruff==0.16.4; extra == "dev"
+Provides-Extra: test
+Requires-Dist: colorama==0.4.6; extra == "test"
+Requires-Dist: pytest==9.1.1; extra == "test"
+Requires-Dist: pytest-cov==7.1.0; extra == "test"
+Requires-Dist: pytest-xdist==3.8.0; extra == "test"
+Provides-Extra: package
+Requires-Dist: build==1.5.0; extra == "package"
+Requires-Dist: colorama==0.4.6; extra == "package"
+Requires-Dist: pefile==2024.8.26; extra == "package"
+Requires-Dist: pyinstaller==6.22.2; extra == "package"
+Requires-Dist: pywin32-ctypes==0.2.3; extra == "package"
+Provides-Extra: docs
+Requires-Dist: mkdocs-material==9.7.7; extra == "docs"
+Dynamic: license-file
+
+# joplin-md-sync
+
+Safe two-way synchronization between the local [Joplin](https://joplinapp.org/)
+desktop application and an ordinary directory of Markdown files — built
+primarily for **autonomous coding agents** (deterministic JSON output, stable
+exit codes, explicit conflict handling), and perfectly usable by humans.
+
+**Documentation:** [joplin-mcp.romancello.net](https://joplin-mcp.romancello.net/)
+
+> **Safety first.** The tool never overwrites divergent edits, never deletes
+> anything without an explicit flag, never uses permanent deletion in Joplin,
+> verifies every write after applying it, and journals every mutating run so
+> interrupted syncs are recoverable. `diff` never mutates anything.
+
+The test-backed definitions of these guarantees live in the
+[contract catalog](https://joplin-mcp.romancello.net/contracts/).
+
+If you are an agent (or configuring one), start with
+**[AGENTS.md](https://github.com/kogeler/joplin-md-sync/blob/main/AGENTS.md)**.
+
+## How it works
+
+- Notes are plain `.md` files; each carries a one-line metadata header with
+  the Joplin id, title, and tags. Notebooks are directories with a
+  `.joplin-folder.json`.
+- Sync state (base snapshots for true three-way comparison) lives in
+  `.joplin-sync/state.sqlite3` inside the workspace — never committed to Git.
+- All communication uses the documented local
+  [Joplin Data API](https://joplinapp.org/help/api/references/rest_api/)
+  (Web Clipper service); Joplin's own database and sync targets are never
+  touched.
+
+## Installation
+
+Source, wheel, and zipapp installations require CPython **>= 3.13** on
+Windows or Linux. Native release executables include Python and have no
+external runtime dependencies.
+
+```bash
+python -m pip install "joplin-md-sync==1.5.5"
+# or: pipx install "joplin-md-sync==1.5.5"
+# or download joplin-md-sync.pyz from a release and: python joplin-md-sync.pyz --help
+```
+
+Native GitHub Release assets:
+
+| Platform | Architecture | Asset |
+| --- | --- | --- |
+| Linux | AMD64 | `joplin-md-sync-linux-amd64` |
+| Linux | ARM64 | `joplin-md-sync-linux-arm64` |
+| Windows | AMD64 | `joplin-md-sync-windows-amd64.exe` |
+
+On Linux, mark the downloaded executable as executable before running it:
+
+```bash
+chmod +x joplin-md-sync-linux-amd64
+./joplin-md-sync-linux-amd64 version
+```
+
+From a checkout, everything is driven by the Makefile:
+
+```bash
+make venv        # runtime venv/ with the CLI installed (venv/bin/joplin-md-sync)
+make venv-dev    # Linux quality tools (ruff, mypy, Bandit, pip-audit)
+make venv-test   # cross-platform pytest tools
+make venv-package # cross-platform PyInstaller and build tools
+make check       # lint + typecheck + full test suite
+make freeze-check # verify all generated dependency locks are current
+make test-live   # opt-in real-Joplin MCP + GPT Actions suites; reads ./token
+make test TEST_WORKERS=8  # override automatic parallel test workers
+make package     # wheel, sdist, .pyz, current-platform executable, checksums
+make help        # all targets
+```
+
+The version's single source is the root `.version` file; runtime
+dependencies are declared in `pyproject.toml` (none by design). Direct tools are
+pinned to their latest stable compatible releases in purpose-specific quality,
+test, package, and docs groups. The four committed `pip-compile` locks include
+SHA-256 hashes and are checked for drift in CI; Windows jobs install only the
+cross-platform test or package lock they need.
+
+## Five-minute quick start
+
+1. In Joplin: *Tools > Options > Web Clipper* — enable the service, copy the
+   authorization token.
+2. ```bash
+   export JOPLIN_TOKEN=<your token>          # Windows: set JOPLIN_TOKEN=...
+   joplin-md-sync init --root ./notes
+   joplin-md-sync pull --root ./notes
+   ```
+   The token is the only required configuration: the default endpoint
+   `http://127.0.0.1:41184` is built in (override with `JOPLIN_BASE_URL`,
+   `JOPLIN_PORT`, `--base-url`, or `--port` when needed).
+3. Edit files under `./notes`, then:
+   ```bash
+   joplin-md-sync diff --root ./notes
+   joplin-md-sync push --root ./notes --dry-run
+   joplin-md-sync push --root ./notes
+   ```
+4. If both sides changed the same note, you get exit code 2 and a conflict
+   bundle: `joplin-md-sync conflicts list` / `conflicts resolve ID --take-local|--take-remote|--merged-file PATH`.
+
+## Agent notes repository template
+
+[`examples/agent-notes-repository/`](https://github.com/kogeler/joplin-md-sync/tree/main/examples/agent-notes-repository) is a
+copyable starter repository for users who want an agent to work on their
+Joplin notes as ordinary Markdown files. It includes:
+
+- a repository-specific `AGENTS.md` with the guarded pull/edit/diff/dry-run/push
+  workflow and an optional MCP setup path;
+- a human runbook that starts with enabling Web Clipper in Joplin Desktop and
+  storing its token outside the sync workspace;
+- a `.gitignore` for credentials, the local standalone binary, and all sync
+  state; and
+- a standard-library installer that downloads the latest compatible native
+  release into `.tools/`, verifies `SHA256SUMS.txt`, and validates the binary
+  before replacing an existing installation.
+
+Start with the template's [README](https://github.com/kogeler/joplin-md-sync/blob/main/examples/agent-notes-repository/README.md),
+not the development instructions for this source checkout.
+
+## MCP and ChatGPT Actions service
+
+One foreground `joplin-md-sync` process exposes MCP and authenticated REST
+Actions from the same tool registry on different URIs. It starts while Joplin
+is offline and recovers on later calls without a restart.
+
+The Actions token is mandatory when Actions are enabled and is reloaded from a
+protected file. MCP bearer authentication remains optional through a separate
+`--auth-token-file`. The headless installer always installs both APIs as one
+`joplin-md-sync.service`; it generates separate mandatory Actions and MCP
+tokens, stores them in protected files, and reports only their paths after a
+successful install. It never creates a separate Actions service.
+
+Use [service installation and operations](https://joplin-mcp.romancello.net/user/SERVICE/) for Linux,
+Windows, credentials, URI isolation, and live tests;
+[MCP API](https://joplin-mcp.romancello.net/user/MCP_API/) for the
+tool contract; and the single [ChatGPT Actions end-to-end
+setup](https://joplin-mcp.romancello.net/user/CHATGPT_ACTIONS/) for endpoint validation, schema export, GPT
+Instructions, editor configuration, and acceptance testing.
+
+## Architecture overview
+
+```
+cli  ->  planner (pure three-way classification: base/local/remote)
+     ->  executor (guard -> apply -> verify -> commit base, journaled)
+api: stdlib urllib client for the Joplin Data API (pagination, retries)
+mcp/actions: two HTTP transports -> shared registry/executor -> Joplin service -> api
+state: SQLite base snapshots, conflicts, tombstones, run journal
+workspace: scanning, atomic writes, backups, quarantine, cross-platform lock
+```
+
+Details in [Architecture](https://joplin-mcp.romancello.net/maintenance/ARCHITECTURE/).
+
+## Supported / not supported (v1)
+
+| Supported | Out of scope |
+| --- | --- |
+| notes, notebooks (nested), tags, binary attachments | editing settings, revisions, or encryption state |
+| two-way sync with conflict bundles | Nextcloud/WebDAV or any direct sync target |
+| resource download/upload/edit through MCP | replacing Joplin's own device sync |
+| crash recovery, backups, quarantine | automatic text merging (only explicit `--merged-file`) |
+| Windows + Linux, Python 3.13/3.14; MCP daemon | filesystem watch mode, native mobile CLI, self-update, permanent note/notebook deletion |
+
+## Versioning
+
+Semantic versioning; Git tags `vX.Y.Z` with GitHub releases carrying the
+wheel, sdist, `.pyz`, native executables, and SHA-256 checksums.
+The same wheel and sdist are published to PyPI through Trusted Publishing.
+`joplin-md-sync update-check --json` compares the installed version against
+the latest stable release
+(exit 8 when outdated). JSON output, exit codes, and the state schema are
+versioned and stable across patch releases. See
+[CHANGELOG.md](https://github.com/kogeler/joplin-md-sync/blob/main/CHANGELOG.md).
+
+## License
+
+[MIT](https://github.com/kogeler/joplin-md-sync/blob/main/LICENSE).

joplin_md_sync-1.5.5/README.md

@@ -0,0 +1,178 @@
+# joplin-md-sync
+
+Safe two-way synchronization between the local [Joplin](https://joplinapp.org/)
+desktop application and an ordinary directory of Markdown files — built
+primarily for **autonomous coding agents** (deterministic JSON output, stable
+exit codes, explicit conflict handling), and perfectly usable by humans.
+
+**Documentation:** [joplin-mcp.romancello.net](https://joplin-mcp.romancello.net/)
+
+> **Safety first.** The tool never overwrites divergent edits, never deletes
+> anything without an explicit flag, never uses permanent deletion in Joplin,
+> verifies every write after applying it, and journals every mutating run so
+> interrupted syncs are recoverable. `diff` never mutates anything.
+
+The test-backed definitions of these guarantees live in the
+[contract catalog](https://joplin-mcp.romancello.net/contracts/).
+
+If you are an agent (or configuring one), start with
+**[AGENTS.md](https://github.com/kogeler/joplin-md-sync/blob/main/AGENTS.md)**.
+
+## How it works
+
+- Notes are plain `.md` files; each carries a one-line metadata header with
+  the Joplin id, title, and tags. Notebooks are directories with a
+  `.joplin-folder.json`.
+- Sync state (base snapshots for true three-way comparison) lives in
+  `.joplin-sync/state.sqlite3` inside the workspace — never committed to Git.
+- All communication uses the documented local
+  [Joplin Data API](https://joplinapp.org/help/api/references/rest_api/)
+  (Web Clipper service); Joplin's own database and sync targets are never
+  touched.
+
+## Installation
+
+Source, wheel, and zipapp installations require CPython **>= 3.13** on
+Windows or Linux. Native release executables include Python and have no
+external runtime dependencies.
+
+```bash
+python -m pip install "joplin-md-sync==1.5.5"
+# or: pipx install "joplin-md-sync==1.5.5"
+# or download joplin-md-sync.pyz from a release and: python joplin-md-sync.pyz --help
+```
+
+Native GitHub Release assets:
+
+| Platform | Architecture | Asset |
+| --- | --- | --- |
+| Linux | AMD64 | `joplin-md-sync-linux-amd64` |
+| Linux | ARM64 | `joplin-md-sync-linux-arm64` |
+| Windows | AMD64 | `joplin-md-sync-windows-amd64.exe` |
+
+On Linux, mark the downloaded executable as executable before running it:
+
+```bash
+chmod +x joplin-md-sync-linux-amd64
+./joplin-md-sync-linux-amd64 version
+```
+
+From a checkout, everything is driven by the Makefile:
+
+```bash
+make venv        # runtime venv/ with the CLI installed (venv/bin/joplin-md-sync)
+make venv-dev    # Linux quality tools (ruff, mypy, Bandit, pip-audit)
+make venv-test   # cross-platform pytest tools
+make venv-package # cross-platform PyInstaller and build tools
+make check       # lint + typecheck + full test suite
+make freeze-check # verify all generated dependency locks are current
+make test-live   # opt-in real-Joplin MCP + GPT Actions suites; reads ./token
+make test TEST_WORKERS=8  # override automatic parallel test workers
+make package     # wheel, sdist, .pyz, current-platform executable, checksums
+make help        # all targets
+```
+
+The version's single source is the root `.version` file; runtime
+dependencies are declared in `pyproject.toml` (none by design). Direct tools are
+pinned to their latest stable compatible releases in purpose-specific quality,
+test, package, and docs groups. The four committed `pip-compile` locks include
+SHA-256 hashes and are checked for drift in CI; Windows jobs install only the
+cross-platform test or package lock they need.
+
+## Five-minute quick start
+
+1. In Joplin: *Tools > Options > Web Clipper* — enable the service, copy the
+   authorization token.
+2. ```bash
+   export JOPLIN_TOKEN=<your token>          # Windows: set JOPLIN_TOKEN=...
+   joplin-md-sync init --root ./notes
+   joplin-md-sync pull --root ./notes
+   ```
+   The token is the only required configuration: the default endpoint
+   `http://127.0.0.1:41184` is built in (override with `JOPLIN_BASE_URL`,
+   `JOPLIN_PORT`, `--base-url`, or `--port` when needed).
+3. Edit files under `./notes`, then:
+   ```bash
+   joplin-md-sync diff --root ./notes
+   joplin-md-sync push --root ./notes --dry-run
+   joplin-md-sync push --root ./notes
+   ```
+4. If both sides changed the same note, you get exit code 2 and a conflict
+   bundle: `joplin-md-sync conflicts list` / `conflicts resolve ID --take-local|--take-remote|--merged-file PATH`.
+
+## Agent notes repository template
+
+[`examples/agent-notes-repository/`](https://github.com/kogeler/joplin-md-sync/tree/main/examples/agent-notes-repository) is a
+copyable starter repository for users who want an agent to work on their
+Joplin notes as ordinary Markdown files. It includes:
+
+- a repository-specific `AGENTS.md` with the guarded pull/edit/diff/dry-run/push
+  workflow and an optional MCP setup path;
+- a human runbook that starts with enabling Web Clipper in Joplin Desktop and
+  storing its token outside the sync workspace;
+- a `.gitignore` for credentials, the local standalone binary, and all sync
+  state; and
+- a standard-library installer that downloads the latest compatible native
+  release into `.tools/`, verifies `SHA256SUMS.txt`, and validates the binary
+  before replacing an existing installation.
+
+Start with the template's [README](https://github.com/kogeler/joplin-md-sync/blob/main/examples/agent-notes-repository/README.md),
+not the development instructions for this source checkout.
+
+## MCP and ChatGPT Actions service
+
+One foreground `joplin-md-sync` process exposes MCP and authenticated REST
+Actions from the same tool registry on different URIs. It starts while Joplin
+is offline and recovers on later calls without a restart.
+
+The Actions token is mandatory when Actions are enabled and is reloaded from a
+protected file. MCP bearer authentication remains optional through a separate
+`--auth-token-file`. The headless installer always installs both APIs as one
+`joplin-md-sync.service`; it generates separate mandatory Actions and MCP
+tokens, stores them in protected files, and reports only their paths after a
+successful install. It never creates a separate Actions service.
+
+Use [service installation and operations](https://joplin-mcp.romancello.net/user/SERVICE/) for Linux,
+Windows, credentials, URI isolation, and live tests;
+[MCP API](https://joplin-mcp.romancello.net/user/MCP_API/) for the
+tool contract; and the single [ChatGPT Actions end-to-end
+setup](https://joplin-mcp.romancello.net/user/CHATGPT_ACTIONS/) for endpoint validation, schema export, GPT
+Instructions, editor configuration, and acceptance testing.
+
+## Architecture overview
+
+```
+cli  ->  planner (pure three-way classification: base/local/remote)
+     ->  executor (guard -> apply -> verify -> commit base, journaled)
+api: stdlib urllib client for the Joplin Data API (pagination, retries)
+mcp/actions: two HTTP transports -> shared registry/executor -> Joplin service -> api
+state: SQLite base snapshots, conflicts, tombstones, run journal
+workspace: scanning, atomic writes, backups, quarantine, cross-platform lock
+```
+
+Details in [Architecture](https://joplin-mcp.romancello.net/maintenance/ARCHITECTURE/).
+
+## Supported / not supported (v1)
+
+| Supported | Out of scope |
+| --- | --- |
+| notes, notebooks (nested), tags, binary attachments | editing settings, revisions, or encryption state |
+| two-way sync with conflict bundles | Nextcloud/WebDAV or any direct sync target |
+| resource download/upload/edit through MCP | replacing Joplin's own device sync |
+| crash recovery, backups, quarantine | automatic text merging (only explicit `--merged-file`) |
+| Windows + Linux, Python 3.13/3.14; MCP daemon | filesystem watch mode, native mobile CLI, self-update, permanent note/notebook deletion |
+
+## Versioning
+
+Semantic versioning; Git tags `vX.Y.Z` with GitHub releases carrying the
+wheel, sdist, `.pyz`, native executables, and SHA-256 checksums.
+The same wheel and sdist are published to PyPI through Trusted Publishing.
+`joplin-md-sync update-check --json` compares the installed version against
+the latest stable release
+(exit 8 when outdated). JSON output, exit codes, and the state schema are
+versioned and stable across patch releases. See
+[CHANGELOG.md](https://github.com/kogeler/joplin-md-sync/blob/main/CHANGELOG.md).
+
+## License
+
+[MIT](https://github.com/kogeler/joplin-md-sync/blob/main/LICENSE).

joplin_md_sync-1.5.5/docs/contracts/AGENT_INTERFACES.md

@@ -0,0 +1,129 @@
+<!-- Copyright (c) 2026 kogeler. SPDX-License-Identifier: MIT. -->
+
+# Agent Interface Contract
+
+## Assertions
+
+### `AIF-001` - One immutable registry owns every agent operation
+
+**Contract:** MCP and GPT Actions MUST derive tool names, schemas, effects,
+handlers, and exposure from one ordered immutable registry and invoke handlers
+through one validating executor. HTTP adapters MUST NOT maintain a second
+operation list or bypass schema validation and failure classification.
+
+**Evidence:**
+
+- [`test_registry_is_ordered_exact_and_deeply_immutable`](../../tests/unit/test_tool_registry.py) - `tests/unit/test_tool_registry.py::test_registry_is_ordered_exact_and_deeply_immutable`
+- [`test_effect_and_route_are_centralized`](../../tests/unit/test_tool_registry.py) - `tests/unit/test_tool_registry.py::test_effect_and_route_are_centralized`
+- [`test_executor_validates_and_preserves_domain_errors`](../../tests/unit/test_tool_registry.py) - `tests/unit/test_tool_registry.py::test_executor_validates_and_preserves_domain_errors`
+- [`test_generated_operations_match_exposed_registry`](../../tests/unit/test_gpt_openapi.py) - `tests/unit/test_gpt_openapi.py::test_generated_operations_match_exposed_registry`
+
+### `AIF-002` - MCP follows the advertised Streamable HTTP lifecycle
+
+**Contract:** `mcp serve` MUST expose MCP Streamable HTTP on loopback
+`/mcp` by default, negotiate only its supported protocol versions, implement
+initialize/initialized, tools/list, and tools/call, and return both text content
+and `structuredContent`. The server MUST advertise itself through CLI
+capabilities and MUST NOT require a Markdown workspace.
+
+**Evidence:**
+
+- [`test_lifecycle_and_transport_contract`](../../tests/integration/test_mcp_server.py) - `tests/integration/test_mcp_server.py::McpHttpTest::test_lifecycle_and_transport_contract`
+- [`test_capabilities_advertise_mcp`](../../tests/integration/test_mcp_server.py) - `tests/integration/test_mcp_server.py::McpCliSafetyTest::test_capabilities_advertise_mcp`
+
+### `AIF-003` - MCP exposes complete Joplin object workflows
+
+**Contract:** MCP MUST support validated note, notebook, tag, and resource
+read/write workflows, relationship traversal, search, trash/restore for notes
+and notebooks, and permanent deletion only where Joplin has no trash API.
+Binary content MUST enter and leave as bounded base64 data, never a server-side
+path. Explicit create operations MUST compare their normalized natural
+identity before mutation, including matching trashed objects, and MUST return a
+non-retryable `*_ALREADY_EXISTS` error with every existing ID and the matching
+update tool rather than create or silently reuse a duplicate. Create preflight
+and mutation MUST be serialized within one bridge process.
+
+**Evidence:**
+
+- [`test_note_crud_metadata_tags_and_search`](../../tests/integration/test_mcp_server.py) - `tests/integration/test_mcp_server.py::McpHttpTest::test_note_crud_metadata_tags_and_search`
+- [`test_notebook_crud_nesting_notes_trash_and_restore`](../../tests/integration/test_mcp_server.py) - `tests/integration/test_mcp_server.py::McpHttpTest::test_notebook_crud_nesting_notes_trash_and_restore`
+- [`test_tag_crud_listing_and_note_relations`](../../tests/integration/test_mcp_server.py) - `tests/integration/test_mcp_server.py::McpHttpTest::test_tag_crud_listing_and_note_relations`
+- [`test_resource_crud_content_and_note_relations`](../../tests/integration/test_mcp_server.py) - `tests/integration/test_mcp_server.py::McpHttpTest::test_resource_crud_content_and_note_relations`
+- [`test_create_note_from_html_and_with_binary_attachments`](../../tests/integration/test_mcp_server.py) - `tests/integration/test_mcp_server.py::McpHttpTest::test_create_note_from_html_and_with_binary_attachments`
+- [`test_create_tools_reject_existing_object_identities`](../../tests/integration/test_mcp_server.py) - `tests/integration/test_mcp_server.py::McpHttpTest::test_create_tools_reject_existing_object_identities`
+- [`test_notebook_title_resolves_only_one_root_destination`](../../tests/integration/test_mcp_server.py) - `tests/integration/test_mcp_server.py::McpHttpTest::test_notebook_title_resolves_only_one_root_destination`
+- [`test_concurrent_note_create_allows_exactly_one_object`](../../tests/integration/test_mcp_server.py) - `tests/integration/test_mcp_server.py::McpHttpTest::test_concurrent_note_create_allows_exactly_one_object`
+- [`test_create_rejects_matching_trashed_note_and_notebook`](../../tests/integration/test_mcp_server.py) - `tests/integration/test_mcp_server.py::McpHttpTest::test_create_rejects_matching_trashed_note_and_notebook`
+- [`test_existing_note_create_returns_conflict_with_update_target`](../../tests/integration/test_gpt_actions.py) - `tests/integration/test_gpt_actions.py::GptActionsHttpTest::test_existing_note_create_returns_conflict_with_update_target`
+- [`test_ambiguous_notebook_title_returns_candidate_ids`](../../tests/integration/test_gpt_actions.py) - `tests/integration/test_gpt_actions.py::GptActionsHttpTest::test_ambiguous_notebook_title_returns_candidate_ids`
+- [`test_02_explicit_creates_reject_existing_natural_identities`](../../tests_live/test_mcp_live.py) - `tests_live/test_mcp_live.py::LiveMcpTest::test_02_explicit_creates_reject_existing_natural_identities`
+- [`test_02_explicit_creates_reject_existing_natural_identities`](../../tests_live/test_gpt_actions_live.py) - `tests_live/test_gpt_actions_live.py::LiveGptActionsTest::test_02_explicit_creates_reject_existing_natural_identities`
+
+### `AIF-004` - Invalid operations fail before side effects
+
+**Contract:** Tool definitions and instances MUST pass the supported JSON
+Schema subset before handler execution. Unknown objects, invalid content,
+unsupported combinations, and Joplin failures MUST return structured stable
+domain errors rather than transport crashes or partial writes.
+
+**Evidence:**
+
+- [`test_schema_definition_and_instance_validation`](../../tests/unit/test_tool_registry.py) - `tests/unit/test_tool_registry.py::test_schema_definition_and_instance_validation`
+- [`test_entity_and_content_validation_errors_are_structured`](../../tests/integration/test_mcp_server.py) - `tests/integration/test_mcp_server.py::McpHttpTest::test_entity_and_content_validation_errors_are_structured`
+- [`test_http_and_schema_validation_precede_side_effects`](../../tests/integration/test_gpt_actions.py) - `tests/integration/test_gpt_actions.py::GptActionsHttpTest::test_http_and_schema_validation_precede_side_effects`
+
+### `AIF-005` - Joplin outages do not terminate the bridge
+
+**Contract:** Binding the agent listener MUST NOT require Joplin availability.
+Each call MAY perform a bounded availability wait and retry reads. An outage
+MUST return a retryable structured tool error and later calls MUST recover.
+Writes MUST be sent once after preflight; ambiguous outcomes MUST be
+non-retryable and exposed for operator inspection.
+
+**Evidence:**
+
+- [`test_joplin_outage_is_retryable_tool_error_and_server_recovers`](../../tests/integration/test_mcp_server.py) - `tests/integration/test_mcp_server.py::McpHttpTest::test_joplin_outage_is_retryable_tool_error_and_server_recovers`
+- [`test_executor_classifies_expected_failures`](../../tests/unit/test_tool_registry.py) - `tests/unit/test_tool_registry.py::test_executor_classifies_expected_failures`
+
+### `AIF-006` - Actions authentication is independent and fail-closed
+
+**Contract:** GPT Actions MUST remain disabled unless explicitly enabled with
+a dedicated protected bearer file. Authentication MUST occur before route
+lookup, files MUST be re-read per request for rotation, malformed or duplicate
+authorization MUST fail closed, and Joplin, MCP, and Actions credentials MUST
+remain independent.
+
+**Evidence:**
+
+- [`test_authentication_is_uniform_independent_and_rotatable`](../../tests/integration/test_gpt_actions.py) - `tests/integration/test_gpt_actions.py::GptActionsHttpTest::test_authentication_is_uniform_independent_and_rotatable`
+- [`test_malformed_and_duplicate_authorization_fail_closed`](../../tests/integration/test_gpt_actions.py) - `tests/integration/test_gpt_actions.py::GptActionsHttpTest::test_malformed_and_duplicate_authorization_fail_closed`
+- [`test_route_is_fail_closed_and_auth_hides_route_details`](../../tests/integration/test_gpt_actions.py) - `tests/integration/test_gpt_actions.py::GptActionsHttpTest::test_route_is_fail_closed_and_auth_hides_route_details`
+- [`test_mcp_actions_and_joplin_credentials_are_independent`](../../tests/integration/test_gpt_actions.py) - `tests/integration/test_gpt_actions.py::GptActionsHttpTest::test_mcp_actions_and_joplin_credentials_are_independent`
+
+### `AIF-007` - OpenAPI is generated, deterministic, and secret-free
+
+**Contract:** The Actions OpenAPI 3.1 document MUST be generated from the
+exposed registry for one strict production HTTPS origin. It MUST be
+deterministic and contain no credential, note data, local path, upstream Joplin
+URL, MCP route, or health route. Disabled operations MUST not be exported.
+
+**Evidence:**
+
+- [`test_contract_is_deterministic_and_secret_free`](../../tests/unit/test_gpt_openapi.py) - `tests/unit/test_gpt_openapi.py::test_contract_is_deterministic_and_secret_free`
+- [`test_production_server_url_is_strict`](../../tests/unit/test_gpt_openapi.py) - `tests/unit/test_gpt_openapi.py::test_production_server_url_is_strict`
+- [`test_cli_exports_contract_and_advertises_optional_transport`](../../tests/unit/test_gpt_openapi.py) - `tests/unit/test_gpt_openapi.py::test_cli_exports_contract_and_advertises_optional_transport`
+
+### `AIF-008` - Public transports enforce bounded resource use
+
+**Contract:** MCP and Actions MUST bound request size, decoded resource size,
+JSON nesting, active handlers, and stalled connections. Actions MUST also
+bound response size, concurrent execution, and authenticated request rate.
+Oversized successful write results MAY be replaced by an explicit omitted
+result but MUST NOT be reported as a failed write.
+
+**Evidence:**
+
+- [`test_pre_auth_connection_count_is_bounded`](../../tests/integration/test_mcp_server.py) - `tests/integration/test_mcp_server.py::McpHttpTest::test_pre_auth_connection_count_is_bounded`
+- [`test_request_limit_and_result_limit_semantics`](../../tests/integration/test_gpt_actions.py) - `tests/integration/test_gpt_actions.py::GptActionsHttpTest::test_request_limit_and_result_limit_semantics`
+- [`test_concurrency_capacity_and_authenticated_rate_limit`](../../tests/integration/test_gpt_actions.py) - `tests/integration/test_gpt_actions.py::GptActionsHttpTest::test_concurrency_capacity_and_authenticated_rate_limit`
+- [`test_json_nesting_limit_is_independent_of_parser_recursion_behavior`](../../tests/unit/test_json_safety.py) - `tests/unit/test_json_safety.py::test_json_nesting_limit_is_independent_of_parser_recursion_behavior`