From 3273049b47b9f67c5907d134e78453cd13d00712 Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Sun, 22 Mar 2026 18:21:24 +0000
Subject: [PATCH] chore: update docs

---
 docs/docs/pages/config.mdx | 1 +
 docs/docs/pages/publishing.mdx | 25 ++++++++++++++++++++++---
 2 file(s) changed, 23 insertion(s)(+), 3 deletion(s)(-)

diff --git a/docs/docs/pages/config.mdx b/docs/docs/pages/config.mdx
--- a/docs/docs/pages/config.mdx
+++ b/docs/docs/pages/config.mdx
@@ -23,6 +23,7 @@
     "publishDate": "date"
   },
   "ignore": ["_index.md"],
+  "autoSync": true,
   "bluesky": {
     "enabled": true,
     "maxAgeDays": 30
diff --git a/docs/docs/pages/publishing.mdx b/docs/docs/pages/publishing.mdx
--- a/docs/docs/pages/publishing.mdx
+++ b/docs/docs/pages/publishing.mdx
@@ -18,15 +18,34 @@
 
 ## Updates
 
-As you publish content Sequoia will store a record of content in `.sequoia-state.json`, keeping track of the AT URIs for each post and generating content hashes for the content inside each markdown file. When you update a post and run the publish command, Sequoia will generate hashes again, see the difference, and update the existing post rather than creating a new one. 
+As you publish content Sequoia will store a record of content in `.sequoia-state.json`, keeping track of the AT URIs for each post and generating content hashes for the content inside each markdown file. When you update a post and run the publish command, Sequoia will generate hashes again, see the difference, and update the existing post rather than creating a new one.
 
-If you happen to loose the state file or if you want to pull down records you already have published, you can use the `sync` command. 
+### Auto-Sync
+
+By default, Sequoia will automatically sync state from your PDS before publishing when the state file is missing or empty. This prevents duplicate posts when publishing from a fresh clone or CI environment. Auto-sync will:
+
+- Fetch existing documents from your PDS for the configured publication
+- Match them to local files by their URL path
+- Update the local `.sequoia-state.json` with matched records
+- Add `atUri` to the frontmatter of matched posts if not already present
+
+To disable auto-sync, set `autoSync` to `false` in your config:
+
+```json
+{
+  "autoSync": false
+}
+```
+
+### Manual Sync
+
+If you want to manually pull down records you already have published, you can use the `sync` command.
 
 ```bash [Terminal]
 sequoia sync
 ```
 
-Sync will use your ATProto handle to look through all of the `standard.site.document` records on your PDS, and pull down the records that are for the publication in the config.
+Sync will use your ATProto handle to look through all of the `site.standard.document` records on your PDS, and pull down the records that are for the publication in the config. Use the `--update-frontmatter` flag to also update your local markdown files with `atUri` fields.
 
 ## Bluesky Posting
 

--
tangled.sh