From d6c7333d37638447a2a41c762574de8851665934 Mon Sep 17 00:00:00 2001
From: t <t@tjp.lol>
Date: Sat, 11 Jul 2026 12:15:04 -0600
Subject: Document deployment and stop tracking generated output

---
 _docs/IMPLEMENTATION_STATUS.md | 30 ++++++++++++++++++
 _docs/OPERATIONS.md            | 70 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 100 insertions(+)
 create mode 100644 _docs/IMPLEMENTATION_STATUS.md
 create mode 100644 _docs/OPERATIONS.md

(limited to '_docs')

diff --git a/_docs/IMPLEMENTATION_STATUS.md b/_docs/IMPLEMENTATION_STATUS.md
new file mode 100644
index 0000000..cc34e80
--- /dev/null
+++ b/_docs/IMPLEMENTATION_STATUS.md
@@ -0,0 +1,30 @@
+# Project implementation status
+
+Status as of 2026-07-11.
+
+- [x] Fictional examples are retained only under underscore-prefixed names and
+  are absent from public listings and the feed.
+- [x] The Weft Go generator, template conventions, Markdown parsing, inventory,
+  link rewriting, output collision checks, relative links, Atom generation,
+  safe output ownership, rollback, and stale cleanup are implemented and
+  covered by runnable tests.
+- [x] Existing pages are represented by templates or Markdown sources and build
+  back to in-place HTML/XML outputs; `style.css` is unchanged.
+- [x] Inherited prose is enumerated in `PROSE_AUDIT.md`; no replacement post
+  prose was invented.
+- [x] The generated site has an empty valid Atom feed, no public fictional
+  entries, and a consistent CC BY 4.0 footer and colophon disclosure.
+- [x] `.gitignore` covers generated HTML, `feed.xml`, the ownership manifest,
+  and transaction directories; shared Syncthing rules exclude generated HTML.
+- [x] Generated HTML and `feed.xml` are ignored and absent from version
+  control, so a fresh checkout can build without bypassing output ownership.
+- [x] Caddy protection and the locked, delayed, failure-logged cron invocation
+  are recorded in `OPERATIONS.md`.
+- [ ] External: install and schedule Weft on the server, activate the Caddy
+  rules, and validate them against the deployed host.
+- [ ] External: connect deliberately selected real vault content and verify its
+  Syncthing/privacy behavior.
+- [ ] External: restore Notes links only after those real notes are ready.
+
+Notes navigation and homepage note links intentionally remain commented out;
+there is no selected real vault content to publish yet.
diff --git a/_docs/OPERATIONS.md b/_docs/OPERATIONS.md
new file mode 100644
index 0000000..a4a6d13
--- /dev/null
+++ b/_docs/OPERATIONS.md
@@ -0,0 +1,70 @@
+# Weft operations
+
+## Caddy source protection
+
+Before enabling public notes, place these matchers before `file_server` in the
+site block and reload Caddy:
+
+```caddyfile
+@underscore path_regexp underscore (^|/)_[^/]*
+respond @underscore 404
+
+@templates path *.tmpl
+respond @templates 404
+```
+
+The first matcher denies any URL with an underscore-prefixed path component,
+including an entire `_private/` subtree. The second denies template sources.
+Markdown is intentionally not denied and may remain downloadable. Validate the
+active configuration with `caddy validate --config /etc/caddy/Caddyfile` before
+`systemctl reload caddy`.
+
+## Syncthing
+
+Each device keeps this device-local, non-synchronized `.stignore` at the vault
+root:
+
+```text
+#include .stignore.shared
+```
+
+The synchronized `.stignore.shared` contains:
+
+```text
+*.html
+```
+
+The local include lets every device load one shared rule without trying to
+synchronize `.stignore` itself. The shared rule excludes generated HTML at
+every depth in both directions while leaving Markdown synchronized.
+
+## Scheduled build
+
+Install the Weft binary at `/usr/local/bin/weft`, then use a cron entry like:
+
+```cron
+17 * * * * sleep 60 && flock -n /run/lock/weft.lock /usr/local/bin/weft /srv/tjp.lol >>/var/log/weft.log 2>&1 || logger -t weft 'build failed or lock unavailable'
+```
+
+The 60-second delay gives Syncthing time to settle, `flock -n` prevents
+overlapping builds, build output goes to `/var/log/weft.log`, and failure is
+also recorded in the system log under the `weft` tag. Adjust the delay only
+after observing the server's real sync latency. These paths assume a root
+crontab; for an unprivileged account, use lock and log paths it can write.
+
+## Rollout
+
+- [ ] Install Weft and run one manual build on the server.
+- [ ] Add and validate the Caddy matchers above before serving the source tree.
+- [ ] Put the local `.stignore` on every Syncthing device and synchronize
+  `.stignore.shared`.
+- [ ] Connect only the deliberately selected public vault content.
+- [ ] Verify generated note pages, internal links, and underscore privacy on the
+  deployed host.
+- [ ] Install the locked, delayed cron build and confirm a forced failure is
+  logged.
+- [ ] Restore Notes navigation and homepage links only after real public notes
+  are present and verified.
+
+Notes remains hidden: no real selected vault content exists in this repository,
+so vault connection and server activation are intentionally pending.
-- 
cgit v1.3