docs: privatize maintainer guidance

Author: ma2za

.gitignore

@@ -110,13 +110,9 @@ ENV/
 env.bak/
 venv.bak/
 
-# removed-provider CLI and Testing artifacts
-.removed-provider/*
-!.removed-provider/.env.example
-!.removed-provider/commands/
-!.removed-provider/commands/**
-!.removed-provider/policies/
-!.removed-provider/policies/**
+# Private maintainer configuration
+removed-provider.md
+docs/removed-provider-removed-provider.md
 tmp_pytest/
 
 # Spyder project settings

CHANGELOG.md

@@ -7,12 +7,9 @@
 - Preserve absolute and home-relative local Markdown image paths during upload,
   retain existing root-relative asset fallback, and report missing files or
   failed uploads instead of saving broken image sources.
-
-## Unreleased
-
-### Fixed
-
-- Return draft records from the Substack drafts response envelope so `drafts list` works with the current API response.
+
+- Return draft records from the Substack drafts response envelope so
+  `drafts list` works with the current API response.
 
 ## 0.8.0
 

README.md

@@ -58,6 +58,7 @@ Substack result:
 - Set audience, comment permissions, SEO metadata, slug, sections, and tags.
 - List and inspect publications and drafts.
 - Export drafts to loss-aware Markdown backups without server writes.
+- Safely update drafts from Markdown, preserving unsupported editor widgets by default.
 - Schedule, unschedule, publish, and delete drafts with explicit safeguards.
 - Use stable JSON envelopes in scripts and automation.
 - Authenticate with browser cookies or email and password.
@@ -109,6 +110,7 @@ substack publications list
 substack drafts list --limit 10
 substack drafts get 12345
 substack drafts export 12345 --output backup.md
+substack drafts update 12345 revised-post.md --dry-run --yes
 substack --publication-url https://example.substack.com drafts list
 ```
 
@@ -181,6 +183,17 @@ print(backup["markdown"])
 print(backup["unsupported_nodes"])
 ```
 
+Review a Markdown update before writing it, then update deliberately:
+
+```python
+result = api.update_draft_from_markdown(12345, "# Revised draft", dry_run=True)
+result = api.update_draft_from_markdown(12345, "# Revised draft")
+```
+
+Unsupported editor widgets exported as `python-substack-node:v1` markers are
+preserved by default. An update refuses to remove or alter them unless
+`allow_unsupported_change=True` is explicitly passed.
+
 For direct ProseMirror node construction, see the
 [low-level Python API](docs/low-level-api.md). YAML workflows are documented in
 [YAML drafts](docs/yaml.md).
@@ -233,11 +246,11 @@ See [MCP server](docs/mcp.md) for the tool list and safety notes.
 - [Python SDK](docs/python-sdk.md)
 - [Authentication](docs/authentication.md)
 - [Markdown reference](docs/markdown.md)
+- [Draft backup and safe updates](docs/cli.md)
 - [Legacy CLI commands](docs/legacy-cli.md)
 - [Low-level Python API](docs/low-level-api.md)
 - [YAML drafts](docs/yaml.md)
 - [MCP server](docs/mcp.md)
-- [removed-provider CLI with removed-provider](docs/removed-provider-removed-provider.md)
 - [Safety and publishing behavior](docs/safety.md)
 - [Troubleshooting](docs/troubleshooting.md)
 - [Compatibility policy](docs/compatibility.md)

docs/cli.md

@@ -36,6 +36,26 @@ It fetches the draft but performs no server writes. Content without a supported
 Markdown representation is emitted as a versioned opaque HTML comment instead
 of being silently discarded.
 
+## Update a draft from Markdown
+
+Preview the generated update without writing to Substack:
+
+```bash
+substack drafts update 12345 revised-post.md --dry-run --yes
+```
+
+Apply it after review:
+
+```bash
+substack drafts update 12345 revised-post.md --yes
+```
+
+Updates preserve unsupported editor nodes exported as
+`python-substack-node:v1` markers. The command refuses to remove or alter
+those nodes by default. `--allow-unsupported-change` is available only with
+`--yes` for an intentional destructive change. The CLI uses its authenticated
+API client while rendering, so local images can upload even during a dry run.
+
 ## Select a publication
 
 List every publication available to the authenticated account:

docs/markdown.md

@@ -197,9 +197,12 @@ their document position as:
 
 The payload is UTF-8 JSON encoded with URL-safe base64 and no padding. This
 makes unsupported content visible and recoverable instead of silently dropping
-it. Version 0.6 does not import these markers into a draft; safe updates that
-preserve them are planned for 0.8.
+it. `Api.update_draft_from_markdown` and `substack drafts update` recognize
+valid markers and preserve the corresponding nodes. They refuse updates that
+remove, duplicate, or alter remote unsupported nodes unless the caller
+explicitly authorizes that change with `allow_unsupported_change=True` or
+`--allow-unsupported-change --yes`.
 
 Export preserves the Markdown meaning of supported images: source, alt text,
 link, and plain-text caption. Substack-only image layout attributes are not a
-Markdown contract in 0.6.
+Markdown contract.

docs/python-sdk.md

@@ -53,3 +53,21 @@ decodable markers.
 
 For supported syntax, see the [Markdown reference](markdown.md). For direct
 editor-node construction, see the [low-level Python API](low-level-api.md).
+
+## Update a draft safely
+
+Preview an update before writing it:
+
+```python
+preview = api.update_draft_from_markdown(
+    12345,
+    "# Revised title\n\nUpdated body.",
+    dry_run=True,
+)
+print(preview["payload"])
+```
+
+Run the same call without `dry_run=True` to write the update. Unsupported
+editor nodes exported as `python-substack-node:v1` markers are preserved by
+default. Removing or changing them raises `ValueError` unless
+`allow_unsupported_change=True` is deliberately supplied.

docs/safety.md

@@ -11,6 +11,7 @@ Creating, scheduling, publishing, and deleting are separate operations.
 |---|---|---|
 | `drafts export` | Reads a draft and produces Markdown | None |
 | `drafts create` | Creates an unpublished draft | None |
+| `drafts update` | Updates a draft from Markdown | Interactive or `--yes` |
 | `drafts schedule` | Adds a future release time | None |
 | `drafts unschedule` | Removes a future release time | None |
 | `drafts publish` | Publishes after a prepublish check | Interactive or `--yes` |
@@ -30,4 +31,6 @@ important source Markdown and verify the selected publication with
 
 Export never writes to Substack and never overwrites a local file unless
 `--force` is supplied. Unsupported editor content is preserved as an opaque
-marker and listed in JSON output so it cannot disappear unnoticed.
+marker and listed in JSON output so it cannot disappear unnoticed. Updates
+refuse to remove or alter those markers unless
+`--allow-unsupported-change --yes` explicitly authorizes it.

docs/troubleshooting.md

@@ -45,7 +45,10 @@ checking the draft ID.
 
 Pass the authenticated `Api` instance to `Post.from_markdown(..., api=api)` or
 use `Api.create_draft_from_markdown`, which does this automatically. Relative
-image paths resolve from the current working directory.
+image paths resolve from the current working directory; absolute paths are
+preserved and `~` expands to the current user's home directory. HTTP(S) and
+protocol-relative image URLs are not uploaded. Missing files and failed
+uploads name the affected path instead of silently retaining a broken source.
 
 If the problem persists, open an issue using the repository's
 [authentication bug form](https://github.com/ma2za/python-substack/issues/new?template=auth_bug.yml)