Managing this website

You keep therighteousremnant.org current by telling your AI tool what to change. Your tool handles the files and commands. AGENTS.md is its rulebook; this guide explains your everyday routine. You can also read this manual at /manage.

Who owns what

You, Dennis, look after content: approved wording, biographies, photos, and the facts you want visitors to see. Supply exact names, dates, addresses, and links; your tool must ask about anything you have not confirmed.

Dustin owns the GitHub project and access, Vercel hosting, and the domain. He also handles contact-form email delivery through Resend, including setting RESEND_API_KEY in Vercel, and the donation service unless another owner is explicitly documented. The Support page uses a Little Green Light donation form. Contact Dustin for access, hosting, domain, email delivery, or donation problems. You do not need a Vercel membership to publish through this workflow.

One-time setup

You need a free GitHub account. Accept Dustin’s invitation to the private website project first. Open Terminal on your Mac (Cmd+Space, then type “Terminal”). Follow these steps once on each computer; ask Dustin for help if you get stuck.

1. Install Homebrew, which installs the other tools. Paste its official installer:

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

   Follow the installer prompts, including its printed Next steps to add Homebrew to your terminal’s PATH. That lets the next command find brew.

2. Install the GitHub tool, Git, and Node.js 22:

   brew install gh git node@22

3. Connect your GitHub account before trying to download the private project:

   gh auth login --web --git-protocol https

   Follow the browser sign-in prompts using the account Dustin invited.

4. Download the project into your home folder and open it:

   cd ~
   gh repo clone datawake-dev/righteousremnant && cd righteousremnant

5. Finish the website’s setup:

   bash scripts/setup.sh

   This selects Node.js 22, saves Homebrew and Node’s terminal settings, asks for your name and GitHub email if needed, and installs the website’s dependencies. You can run it again safely. Use this bash command if Node or npm is missing; npm run setup is available once npm works.

Open a new Terminal window after setup. Install your chosen AI tool using its own instructions, sign in, and open ~/righteousremnant in that tool. It must be able to read this folder and run commands on your computer. If that is unclear, ask Dustin to rehearse the first session with you.

Start every AI session with this exact sentence:

Read AGENTS.md and follow it for this whole session.

Four words you will see

• Branch: your separate working copy of the site’s saved changes. main holds the version accepted for publication; your work branch collects a batch.
• Pull request: a batch you send to GitHub to be checked and added to main. A draft pull request shares work without starting publication.
• Merge conflict: two changes touched the same part of a file, so your tool needs to reconcile them before continuing.
• GitHub Actions: the project’s automatic checks and publishing steps on GitHub. A green run means those steps succeeded; a red run needs attention.

Every time you work

1. Start your session

Open your AI tool in the website folder, give it the opening sentence above, and say:

Run npm run start-work and explain any live changes or unpublished work in one sentence.

Your tool runs this for you. It downloads live changes, saves stray edits, and creates or continues your work branch. It reuses an earlier personal branch when that branch still has an open pull request or saved changes that have not been sent. Wait for “Ready” before continuing. If it stops, use Recover safely below so your tool can finish the interrupted step.

2. Describe your changes

Give the exact wording, facts, links, or photos you want. Group related changes into one batch, such as a biography update, a replacement photo, and a typo. Use the copyable requests below or describe the change in your own words.

3. Look at the preview

Run npm run dev and open the preview so I can check the changed pages on a phone-sized and a wide screen.

Open the address the command prints, usually http://localhost:4321. Your preview is on this computer. Look at each changed page, tell your tool what needs adjusting, and confirm when it looks right. Press Ctrl+C in the preview’s Terminal window to stop it when you are finished.

4. Publish the batch

Your tool asks whether to go live now or keep collecting changes. When ready, say this, replacing the description with what your batch actually changes:

Publish this batch with npm run go-live -- "Updated the About page bios and photo".

The command saves the batch, brings in the latest live changes, runs the tests, and builds the site. A failed check stops submission. It then sends one pull request, or updates the existing one and makes it ready if it was a draft. GitHub repeats the checks with the latest main before merging it. Vercel then deploys the site, usually within about two minutes; the history is recorded after the merge and can take another minute to appear.

“GitHub is now checking and publishing this batch” means your batch was submitted. Follow Checking a publish landed before treating it as complete. “There is nothing new to publish” means there is no waiting batch to send.

Requests you will make most

Replace the parts in square brackets with your confirmed facts before pasting.

There is no dedicated Events page or event data file in this project today. Your tool should use the actual content map below when planning a new feature.

Pause, resume, and drafts

To stop without publishing, say:

Keep collecting changes for later. Check and save this batch on the current work branch. Do not send it to GitHub yet. Tell me what is waiting.

Your edits stay on this computer until you send them. To resume later, say:

Run npm run start-work, resume my unfinished batch, and tell me what is still waiting before making new changes.

If you need Dustin to see unfinished work, say:

Run npm test and npm run build, then share this batch as one draft pull request. Keep it a draft until I ask to publish, and give me its link.

Your tool saves and pushes the checked branch, then uses gh pr create --draft if there is no existing pull request. Drafts do not trigger the automatic merge. If a request is already ready, have your tool check its status before trying to pause it: a batch that already merged needs recovery, not a draft conversion.

To finish a draft or retry an unfinished publication, say:

Resume my existing batch with npm run start-work, check its pull request status, and run npm run go-live -- "[accurate batch description]" when the preview is confirmed. Update the existing request and make it ready; do not create a second request for the same batch.

Recover safely

Missing edits after a failed start-work

The command temporarily saves unsaved edits in a Git stash, a named holding place on this computer. If startup fails, it tries to restore that saved copy. If it cannot, it prints the exact stash name and restoration command. Keep that output and tell your tool:

My edits seem missing after npm run start-work failed. Read the error and its stash recovery command. Inspect git status and git stash list, identify my saved edits, and restore them safely. Resolve any conflicts without discarding either version. Do not delete a stash until you confirm my edits are back.

For an older failure without a printed name, your tool should inspect the existing stashes to find the right one. Do not run cleanup commands or discard files to make the error disappear.

Sign-in failures

Help me fix this GitHub sign-in failure: [error]. Check gh auth status, guide me through gh auth login --web --git-protocol https if needed, and confirm I am using the account Dustin invited. Then retry the interrupted command without losing my edits.

Contact Dustin if the account lacks access. Keep passwords and access tokens out of your prompts, saved files, and screenshots.

Merge conflicts

Resolve this merge conflict while preserving my intended changes and the latest live changes. Explain which wording you kept and why, ask me about uncertain facts, then rerun the command that stopped.

Your tool handles the files. You do not need to type Git commands yourself.

Failed tests or build

Read this test or build failure: [error]. Fix the cause, run npm test and npm run build again, and show me the preview before retrying npm run go-live. Do not skip the failing check.

If the local command stopped before sending, that attempt sent no changes. If GitHub failed after submission, ask your tool to inspect the failed Actions step: a history failure can occur after the site change has already merged.

Undo a published batch

Find the unwanted batch in /manage/history. Tell your tool:

Run npm run start-work. Find and inspect the published batch titled [title] from [date], identify its merge commit, and undo it on my work branch with git revert -m 1 <merge commit>. Do not assume the newest commit is that batch. Preserve later work where possible, run npm test and npm run build, and show me the preview before publishing the reversal with npm run go-live when I confirm it.

Your tool substitutes the actual merge identifier. This creates a new saved change that reverses that batch; it keeps the history of what happened. Never use a force-push or erase published history. Contact Dustin for an outage or an urgent hosting rollback.

Contact messages or donations are not working

Check the receiving inbox and spam folder for a contact message. Tell your tool:

Check the Contact page and src/pages/api/contact.ts without printing secrets. Ask Dustin to confirm Resend delivery and RESEND_API_KEY in Vercel. Guide me through sending one harmless test message from the live page and confirming it actually arrives.

A success message on the page alone does not prove email arrived. A local preview without Dustin’s Resend configuration does not prove live delivery.

For donations, open the Support page and its direct donation-form link. Say:

Check that the Support page’s Little Green Light form and direct link load the intended donation form. Ask Dustin about any service or account problem. Do not change the donation destination or make a test payment without explicit approval.

Checking a publish landed

Check the stages separately:

1. Submitted: go-live prints a pull request link and says GitHub is checking the batch. The batch has reached GitHub.
2. Merged: that pull request shows Merged. Its tests and integrated build passed, and the batch was added to main.
3. Deployed: Vercel has put the change online. Open the actual changed page at therighteousremnant.org and check it.
4. Recorded: the batch appears in /manage/history. The history update runs after the merge and needs its own deployment, so it may appear later than the page change. Recording and the first deployment can overlap.

Check my batch titled [title]: confirm its pull request is merged, inspect the GitHub Actions run and Vercel deployment status if available, check its entry in /manage/history, and open the actual changed live page. Tell me which stage is still waiting or failed.

If nothing changes after a few minutes, check the project’s GitHub Actions page. Ask your tool to read the failed step and explain it, or contact Dustin. A green Actions run confirms the checks, merge, and history step succeeded; you still need to check the deployed page.

Public history and privacy

The manual and history can be read by anyone with their addresses, even though these pages are left out of search listings. Keep private information out of both.

Only names listed in content/contributors.json appear as author names in public history. Unlisted authors display as Contributor. Approved automation is labeled automatic. Email addresses are removed from history text, but names and other private details in pull-request titles and saved-change descriptions are not automatically removed. Keep those descriptions suitable for the public.

To list a collaborator, confirm their preferred public name and tell your tool:

Add this approved collaborator to content/contributors.json: public display name [name], saved Git author name or matching aliases [aliases], and kind person. Keep existing entries. Run the history tests and generator, and check that no unapproved identity appears.

Your tool adds an object with match (the list of identity aliases), name (the approved public display name), and kind (person). Matching ignores capitalization and uses the saved author name, or the email only if no name exists. Do not guess identities or copy private account details into this manual.

The title in history comes from the pull-request title, normally the description passed to go-live. Use “Updated the About page bios,” not “updates.” The expanded details come from saved-change descriptions. The history file is generated automatically; do not edit content/changelog.json by hand.

Environment files and node_modules must stay out of saved batches. The everyday commands unselect those files and stop if they were staged, even when an ignore rule was bypassed. Ask your tool to fix the cause before continuing.

Complete content map

Your tool handles these files; use this map to point it toward the right place.

Colors and fonts

The existing palette uses forest for dark green, sage for medium green, cream for the warm off-white background, parchment for alternate sections, and charcoal for near-black. Headings use Cormorant Garamond; body text uses DM Sans. Ask your tool to follow the site’s existing styles when making changes.