Reference Operations / External Content Sync

CTX Better Auth Repo Update

Instructions for refreshing the local and GitLab-hosted Better Auth documentation context repository. Better Auth as the authentication framework for user accounts, login, sessions, and account-access control.

Text size
Status: publishedCreated: 06/28/2026Last updated: 06/28/2026

Document Scope

Just Headlines uses Better Auth as the authentication framework for user accounts, login, sessions, and account-access control.

This document defines the repeatable process for updating the Just Headlines Better Auth documentation context repository. The purpose of this task is to keep a small, focused copy of the Better Auth documentation available inside the Just Headlines development environment so human developers, Codex sessions, AI agents, and future MCP/RAG tooling can read the relevant authentication documentation locally without repeatedly relying on external website lookups or pasted documentation links.

This document is written for both human operators and AI agents. It explains what the local context repository is, why it exists, what source path is copied from the upstream Better Auth GitHub repository, and what PowerShell block should be run whenever the documentation context needs to be refreshed.

1. Purpose

The Better Auth documentation context repository exists so that Just Headlines has a local and GitLab-hosted copy of the Better Auth documentation needed during authentication-layer development.

The upstream Better Auth repository contains more source code, packages, tests, tags, branches, and project history than Just Headlines needs for routine authentication planning. This context repository intentionally stores only the documentation path needed for development reference.

The selected upstream path is:

docs/content/docs

The local Just Headlines context repository is:

C:\dev\ctx-better-auth

The temporary source checkout used during refresh is:

C:\dev\_better-auth-source

The GitLab context repository remote is:

git@gitlab-sudostac:sudostac/ctx-better-auth.git

2. Operational Use

Run this task whenever the Better Auth documentation context should be refreshed from the upstream developer repository.

This may be done manually during active authentication-layer development, especially before asking Codex or another AI coding agent to rely on Better Auth implementation details.

After this task runs successfully, the local folder at C:\dev\ctx-better-auth should contain the latest copied documentation content from Better Auth's upstream docs/content/docs path, and the GitLab repository should contain a committed copy of that same documentation context.

3. Source and Destination

Source repository:

https://github.com/better-auth/better-auth.git

Included upstream path:

docs/content/docs

Local context repository:

C:\dev\ctx-better-auth

GitLab destination repository:

git@gitlab-sudostac:sudostac/ctx-better-auth.git

Temporary local source checkout:

C:\dev\_better-auth-source

4. What This Script Does

This script performs the following task sequence:

  1. Removes the temporary upstream checkout folder if it already exists.
  2. Creates a fresh sparse checkout of the upstream Better Auth GitHub repository.
  3. Pulls only the docs/content/docs path from the upstream repository.
  4. Captures the upstream commit hash used for the refresh.
  5. Removes the previously stored local documentation context.
  6. Copies the latest selected documentation into C:\dev\ctx-better-auth\docs.
  7. Ensures the local context folder is a Git repository.
  8. Ensures the GitLab SSH remote is set correctly.
  9. Stages the refreshed documentation context.
  10. Creates a verbose Git commit only if the documentation content changed.
  11. Pushes the update to GitLab.
  12. Deletes the temporary upstream checkout folder.
  13. Shows the final Git status.

5. PowerShell Refresh Script

Run this block from a normal PowerShell window.

$ErrorActionPreference = "Stop"

$LocalRepo = "C:\dev\ctx-better-auth"
$TempSource = "C:\dev\_better-auth-source"
$UpstreamRepo = "https://github.com/better-auth/better-auth.git"
$IncludedPath = "docs/content/docs"
$GitLabRemote = "git@gitlab-sudostac:sudostac/ctx-better-auth.git"

cd C:\dev

Remove-Item -Recurse -Force $TempSource -ErrorAction SilentlyContinue

git clone --filter=blob:none --sparse $UpstreamRepo $TempSource

cd $TempSource
git sparse-checkout set $IncludedPath
$UpstreamCommit = git rev-parse --short HEAD

Remove-Item -Recurse -Force "$LocalRepo\docs" -ErrorAction SilentlyContinue
New-Item -ItemType Directory -Force $LocalRepo | Out-Null
Copy-Item -Recurse "$TempSource\docs\content\docs" "$LocalRepo\docs"

cd $LocalRepo

if (-not (Test-Path ".git")) {
    git init
    git branch -M main
}

git remote get-url origin *> $null
if ($LASTEXITCODE -ne 0) {
    git remote add origin $GitLabRemote
} else {
    git remote set-url origin $GitLabRemote
    git remote set-url --push origin $GitLabRemote
}

git add -A
git diff --cached --quiet

if ($LASTEXITCODE -eq 0) {
    Write-Host "No Better Auth documentation changes to commit."
} else {
    $CommitBody = @"
Refreshes the local GitLab context copy of the Better Auth documentation used for authentication implementation reference.

Changed behavior:
- Replaces the stored Better Auth documentation context with the latest upstream copy.
- Stores only the Better Auth docs/content/docs documentation path.
- Excludes the rest of the upstream Better Auth repository from this context repository.
- Keeps the context repository small, readable, and focused on authentication documentation.

Source:
- Upstream repository: https://github.com/better-auth/better-auth.git
- Included path: docs/content/docs
- Upstream commit: $UpstreamCommit

Operational context:
- Maintains an updated local and GitLab-hosted documentation context for Better Auth.
- Supports local review, Codex access, future documentation indexing, and future MCP/RAG workflows.
- Avoids storing the full upstream Better Auth source tree when only the documentation path is needed.

Validation performed:
- Pulled the selected documentation path from the upstream Better Auth repository.
- Replaced the local documentation context with the latest selected upstream content.
- Staged only the resulting context-repository changes.
"@

    git commit -m "Update Better Auth documentation context" -m "$CommitBody"
    git push origin main
}

Remove-Item -Recurse -Force $TempSource -ErrorAction SilentlyContinue

git status

6. Expected Result

If the upstream Better Auth documentation changed, the script should create and push a new commit with this subject:

Update Better Auth documentation context

If the upstream Better Auth documentation did not change, the script should print:

No Better Auth documentation changes to commit.

In either case, the final git status should show the current state of the local context repository.

7. AI Agent Instructions

When using this repository for authentication-layer development, AI agents should treat C:\dev\ctx-better-auth\docs as the local Better Auth documentation context.

AI agents should use this local repository as the first reference source for Better Auth documentation during Just Headlines authentication work. The upstream Better Auth website or GitHub repository may still be used when the local context appears incomplete, stale, or insufficient for a specific implementation question.

Do not assume that this repository contains the full Better Auth source tree. It is intentionally limited to the selected documentation path.

8. Human Operator Notes

This script is safe to run repeatedly. It replaces the stored documentation context with a fresh copy of the selected upstream documentation path.

The script does not store SSH keys, passphrases, tokens, Better Auth secrets, Just Headlines secrets, or application configuration secrets. Git authentication is handled by the existing local SSH configuration on the operator's computer.

If GitLab blocks a push because the branch is protected, check the GitLab branch protection settings for the ctx-better-auth repository and confirm that normal pushes to main are permitted for the account performing this task.

9. Validation Checklist

After running the script, confirm the following:

  1. C:\dev\ctx-better-auth\docs exists.
  2. The folder contains Better Auth documentation files from the upstream docs/content/docs path.
  3. git status does not show unexpected staged changes.
  4. If changes were found, a commit was created.
  5. If a commit was created, it was pushed to git@gitlab-sudostac:sudostac/ctx-better-auth.git.
  6. The temporary folder C:\dev\_better-auth-source was removed.

10. Related Repositories

This document concerns the documentation context repository only:

C:\dev\ctx-better-auth

It does not define the Just Headlines authentication implementation itself. The implementation belongs in the applicable Just Headlines application repository.