Pro Church Tools — Company OS

pctos.com Runbook

7 min read

pctos.com Runbook

For Brady: When something breaks, start here. Each section is a symptom → diagnosis → fix.

”I edited a file in Clearly and pctos.com isn’t reflecting the change”

The pipeline has four stages — failures can happen at any of them. Diagnose in order:

Stage 1 — Did iCloud sync the change?

ls -la "/Users/bradyshearer/Library/Mobile Documents/com~apple~CloudDocs/company-os/<your-file>.md"

The last modified timestamp should match when you saved in Clearly. If it doesn’t:

  • iCloud might be paused or the device offline. Check System Settings → Apple ID → iCloud → iCloud Drive.
  • Force a sync: brctl monitor com.apple.CloudDocs for activity, or just open Finder and navigate to the folder.

Stage 2 — Did the launchd job pick it up?

tail -50 ~/Library/Logs/company-os-sync.log

You should see entries every hour. The most recent entry should mention either “no diff, skipping” (if you edited mid-hour) or “committed and pushed” (if it picked up a change).

If the log hasn’t updated in over an hour:

launchctl list | grep com.bradyshearer.company-os-sync

If empty: the job isn’t loaded. See “How to (re)install the sync job” below.

If loaded but not running on schedule: check LastExitStatus in the launchctl output. Non-zero means the script errored.

Stage 3 — Did GitHub receive the push?

gh repo view bradyshearer/company-os --web

Click into the file you edited. The latest commit on that file should match what you saved in Clearly.

If GitHub doesn’t have it but the launchd log says “committed and pushed”:

  • Auth issue. Check git remote -v shows the right URL. If it’s HTTPS, you may need a personal access token; switch to SSH (git remote set-url origin git@github.com:bradyshearer/company-os.git).

Stage 4 — Did Cloudflare Pages build?

Cloudflare dashboard → Workers & Pages → pctos → Deployments. You should see a deployment kicked off shortly after the GitHub push.

If no deployment was triggered:

  • Cloudflare’s GitHub integration may have lost auth. Pages project → Settings → Build & deployments → reauthorize.

If the deployment ran but failed: see “Cloudflare Pages build fails” below.

If the deployment succeeded but the site doesn’t reflect the change:

  • Hard-refresh the browser (Cmd+Shift+R on Mac).
  • Check Cloudflare’s edge cache: dashboard → Caching → Purge Cache → Purge Everything. Edge caches usually expire in minutes; only purge if it’s persisted.

”Cloudflare Pages build fails”

Open the failed deployment’s logs in the Pages dashboard. Common patterns:

Cannot find module @jackyzha0/quartz

Build command misconfigured. Should be: cd .quartz && npm ci && npx quartz build -d ../ -o ./public. Note the cd .quartz && prefix.

Engine "node" is incompatible

Quartz requires Node 22+. Add environment variable NODE_VERSION=22 in the Pages project settings.

error TS... in the config

Quartz typechecks the config on every build. Run npx tsc --noEmit locally inside .quartz/ to reproduce, fix, commit, push.

Quartz warns about wikilinks pointing at non-existent docs. These are warnings, not errors — they don’t fail the build. Common cause: a [[10-year-plan]] wikilink in a published doc still pointing at an unpublished file.

To find them:

cd .quartz && npx quartz build -d ../ -o ./public 2>&1 | grep -i "warning"

Either fix the source doc (preferred) or accept the warning if the link is intentional.

Filtered out N files higher than expected

Build log shows how many files the publish filter excluded. Expected: 4 (AGENTS, HOW-TO-USE, README, 10-year-plan). If higher, check whether you accidentally added publish: false to a doc that should be public.

”An exec can’t sign in”

  1. Confirm their email is on the Access policy: Zero Trust → Access → Applications → Company OS — pctos.com → policy Executive 7 → check the email list (case-sensitive matters; lowercase is safe)
  2. Confirm they’re checking the right inbox — the magic-link code goes to the email you allow-listed, not necessarily their primary inbox
  3. Codes expire in ~10 minutes; have them request a fresh one
  4. If still stuck: Zero Trust → Logs → Access authentication → search for their email; the failure reason is logged

”A new doc isn’t appearing on the site”

In order of likelihood:

  1. It has publish: false or status: draft in frontmatter. Check the file’s frontmatter.
  2. It’s in templates/ or .quartz/. Those folders are excluded entirely.
  3. It hasn’t been pushed yet. git status to confirm; either wait for the next launchd run (≤ 1 hour) or push manually: git add -A && git commit -m "..." && git push.
  4. The build hasn’t completed. Check Cloudflare deployments.
  5. The wikilink to it is broken. The file might be published but unreachable from any nav link. Add a wikilink from INDEX.md or a folder README.

”A wikilink is rendering as plain text instead of a link”

The link target doesn’t resolve. Either:

  • The target doesn’t exist (typo in the wikilink)
  • The target has publish: false (intentionally unpublished — leave it as plain text)
  • Case mismatch in the file path ([[Index]] won’t resolve to INDEX.md cleanly; use [[INDEX]])

“I want to preview a change before pushing”

Run Quartz locally with --serve:

cd ~/Library/Mobile\ Documents/com~apple~CloudDocs/company-os/.quartz
npx quartz build -d ../ --serve

Open http://localhost:8080. Edit a markdown file in Clearly; the local server hot-reloads.

When the preview looks right, git add -A && git commit && git push.

How to (re)install the sync job

The plist lives at ~/Library/LaunchAgents/com.bradyshearer.company-os-sync.plist and the script at ~/bin/company-os-sync.sh (or wherever you placed it per AGENTS.md → Publishing pipeline).

# Unload (if loaded)
launchctl unload ~/Library/LaunchAgents/com.bradyshearer.company-os-sync.plist 2>/dev/null
 
# Reload
launchctl load ~/Library/LaunchAgents/com.bradyshearer.company-os-sync.plist
 
# Verify it's loaded
launchctl list | grep company-os-sync
 
# Force an immediate run (for testing)
launchctl start com.bradyshearer.company-os-sync
 
# Tail the log
tail -f ~/Library/Logs/company-os-sync.log

If the script itself has a bug, edit the script directly. The launchd job re-reads it on every run.

”Sync log shows fatal: Unable to read current working directory: Operation not permitted”

This is the macOS Full Disk Access (TCC) gotcha for iCloud Drive. Files under ~/Library/Mobile Documents/com~apple~CloudDocs/ are TCC-protected. Processes spawned by launchd don’t inherit your interactive shell’s TCC permissions, so git running under the launchd job can’t read the OS folder.

Fix: grant Full Disk Access to /bin/bash.

  1. Open System Settings → Privacy & Security → Full Disk Access
  2. Click the + (you’ll be prompted for your password)
  3. Press ⌘ + Shift + G in the file picker → paste /bin/bash → Open → Add it
  4. Confirm /bin/bash is now in the list with the toggle ON
  5. Force a sync to verify: 
    launchctl start com.bradyshearer.company-os-sync
sleep 2
tail -20 ~/Library/Logs/company-os-sync.log
    You should see “No changes to commit. Done.” (clean exit) or a successful commit/push.

Alternative (narrower): instead of /bin/bash, add ~/bin/company-os-sync.sh directly. This works on macOS Sonoma+ but can be flaky — /bin/bash is the reliable answer.

Why this isn’t documented in setup: the FDA prompt only fires when something tries to access TCC-protected paths from a non-interactive process. Until the launchd job actually runs, macOS has no reason to prompt. So the failure surfaces on first sync, not at install time.

How to disable the sync temporarily

Useful when you’re doing a heavy refactor and don’t want noisy half-state commits:

launchctl unload ~/Library/LaunchAgents/com.bradyshearer.company-os-sync.plist

Re-enable with launchctl load. While disabled, you can still push manually whenever you want.

Graph View

Backlinks