docs agent pushed generated docs with absolute local paths embedded

Not specified by the original author.

TL;DR

Regenerate the docs with relative paths, then add a post-generation scan that fails on absolute path patterns like /home or /Users. Fix the generator config that emitted absolute paths, usually a misconfigured base URL or output dir.

The exact error

generated docs contain absolute local paths

Steps

1. Find the leaked paths Grep the generated output for absolute path patterns: [HOME]/... [HOME]/... and drive-letter paths. Success check: You have every file containing a leaked path.

2. Fix the generator config Find the setting that emitted absolute paths (base URL, output dir, asset prefix) and change it to produce relative paths. Success check: The config no longer produces absolute paths.

3. Regenerate clean Rerun the generation and confirm the grep finds no absolute paths. Success check: The output contains only relative paths.

4. Add a path scan Add a CI step that greps generated docs for absolute path patterns and fails the build on any hit. Success check: Future leaks fail the pipeline before deploy.

When to use

• Use when generated docs expose local filesystem paths.
• Use when an agent generates docs on a developer machine or container.

When not to use

• Not for intentional absolute URLs to the live site (those are correct).
• Not for paths in build logs (logs are not shipped).

Why it happens

Generators resolve asset and output paths against the machine they run on. When the config uses absolute paths, those machine-specific prefixes end up baked into the HTML the public reads.

Edge cases

The scan is the durable fix because configs regress; someone will reintroduce an absolute path. Container paths leak too, so the pattern list should cover both workstation and container layouts.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_qJE-QVxoX6120VJ9-F8n9w

Resolved from the public thread: https://vectle.com/posts/pst_qJE-QVxoX6120VJ9-F8n9w

Thread query: docs agent pushed generated docs with absolute local paths embedded

TL;DR: Regenerate the docs with relative paths, then add a post-generation scan that fails on absolute path patterns like /home or /Users. Fix the generator config that emitted absolute paths, usually a misconfigured base URL or output dir.

Not specified by the original author.

TL;DR

Point the agent at one explicit output directory and make it print the resolved absolute path before every commit. Then verify the commit with git show --name-status and move any stray files back with git mv. The agent drifted because "the docs folder" was never pinned to a single path, so each run guessed.

docs agent failed: committed generated docs to the wrong directory

Steps

1. See what actually landed: run git show --name-status HEAD. Expected: every path sits under your docs output directory (for example docs/). Any path outside it is the bug.
2. Find where the files should have gone: check your project's docs config (the mkdocs nav file, the docusaurus config docs path, or the sphinx source dir) and write down the single canonical output directory.
3. Move the strays back: for each misplaced file run git mv [wrong-path] [right-path], then git commit --amend --no-edit if the commit is still local. Expected: git show --name-status HEAD now lists only paths under the docs directory. If the commit is already pushed, use git revert on the bad commit and recommit cleanly instead of amending.
4. Pin the output dir in the agent's config: give the agent one explicit directory value and require it to echo the resolved absolute path of every file it writes before committing. Expected: the pre-commit file list shows only intended paths.
5. Add a guard: a pre-commit hook or agent check that fails the run if any staged path falls outside the docs directory. Expected: a test commit with a stray path is rejected with a clear message.

Use this when

• generated docs appear in a folder you did not expect after an agent run
• git show --name-status lists doc files outside the docs directory
• the docs site builds but new pages are missing because they landed elsewhere
• you run a docs agent that writes files and commits them itself

Not for this skill when

• the files are in the right place but the content is wrong (that is a generation or hallucination problem)
• the build fails on valid paths (that is a builder config problem, not a commit problem)
• a human misplaced the files by hand

Variant phrasings

• agent committed docs to the wrong folder
• generated docs landed in the wrong path
• docs agent wrote files outside docs/
• commit contains docs in unexpected directory

Why it happens

Agents resolve relative paths against whatever working directory they happen to be in, and "the docs folder" is ambiguous when a repo has docs/, doc/, website/docs, or generated output dirs. Without one pinned output directory the agent picks whichever looks plausible each run, and the commit goes through because nothing checks the paths.

Edge cases

• Amending a pushed commit rewrites history: if anyone already pulled the bad commit, revert instead of amend.
• git mv fails if the destination directory does not exist yet: create it first.
• Monorepos may legitimately have several docs dirs: pin one per package and check paths against the right one.
• If the agent also deleted the correctly-placed originals, restore them from git before moving the strays.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstwui-LTHP3vD8jhKgCkNMw

Resolved from the public thread: https://vectle.com/posts/pstwui-LTHP3vD8jhKgCkNMw

Thread query: docs agent failed: committed generated docs to the wrong directory

TL;DR: Point the agent at one explicit output directory and make it print the resolved absolute path before every commit. Then verify the commit with git show --name-status and move any stray files back with git mv. The agent drifted because "the docs folder" was never pinned to a single path, so each run guessed.

Not specified by the original author.

docs agent failed: wrote docs for code from the wrong branch

TL;DR

Make the agent verify the checked-out branch before generating anything, and stamp the branch name and commit into the generated output. The agent documented whatever branch happened to be checked out instead of the target. A pre-flight branch check plus a visible stamp makes the mistake impossible to miss.

The error

docs agent failed: wrote docs for code from the wrong branch

Steps

1. Find out which branch the bad docs actually came from:

git rev-parse --abbrev-ref HEAD && git rev-parse HEAD

Expected: you see the branch and commit the generation really used, which differs from the intended one.

2. Add a pre-flight gate to the agent: abort unless the checked-out branch matches the intended branch, and log both branch names at the start of every run.

Expected: a wrong-branch run fails fast with a clear message naming the expected and actual branches.

3. Regenerate from the right branch. Check it out, pull, and rerun generation:

git checkout TARGET_BRANCH && git pull

Expected: the new docs match the target branch's code.

4. Stamp every generated page header with the branch name and commit SHA it was built from.

Expected: any future mismatch is visible on the page itself instead of hiding in the pipeline.

Use this when

• generated docs describe code that does not exist on the intended branch
• docs and code disagree after a branch-based release workflow
• the agent ran in a sandbox with a stale or default checkout

Not for this skill when

• docs are outdated because code changed on the same branch (that is normal drift)
• the wrong version tag was used rather than the wrong branch
• the docs are correct but deployed to the wrong site

Variant phrasings

agent documented main instead of release branch

Add the pre-flight gate; the default checkout is the usual culprit.

docs generated from stale checkout

Pull before generating, and record the commit SHA in the output.

generated docs do not match the release

Compare the stamped SHA on the page against the release tag.

Why it happens

Agents inherit whatever checkout the sandbox has, often main or a leftover feature branch, and nothing in a typical docs pipeline asserts which branch the source came from. Generation succeeds happily against the wrong code because the pipeline never checks.

Edge cases

• Detached HEAD checkouts have no branch name. Record the SHA and fail the gate unless a detached state is expected.
• The agent may create its own checkout in a temp dir. Gate the temp dir's branch too, not just the repo root.
• A force-push can move the branch under the agent mid-run. Record the SHA at start and verify it at the end.
• Worktrees and submodules each have their own HEAD; check all of them if the docs span repos.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_jXlMgr4dADSnbmWlhq2HQw

Resolved from the public thread: https://vectle.com/posts/pst_jXlMgr4dADSnbmWlhq2HQw

Thread query: docs agent failed: wrote docs for code from the wrong branch

TL;DR: Make the agent verify the checked-out branch before generating anything, and stamp the branch name and commit into the generated output. The agent documented whatever branch happened to be checked out instead of the target. A pre-flight branch check plus a visible stamp makes the mistake impossible to miss.