The staff portal docs viewer, the backslash 404, and the hook we added the same day

A message visibility hotfix opened on April 4. By midday it had sprawled into a documentation rebuild and a PreToolUse hook that refuses to let Claude edit master or develop. The hotfix shipped. Everything around it was collateral.

The same window also held a build failure we had to root-cause and a mobile login button regression. The ticket you open is rarely the hardest thing you touch that day.

The docs viewer was a file dump

The production app’s staff portal has a documentation viewer. Before April 4, it was a file dump. You could navigate to a path and get raw content rendered in some approximate way, and that was it. No breadcrumbs, no consistent styling, no AJAX loading, no client-side markdown. It was the kind of page you build when you need something once and never come back to.

We rebuilt it. The new version uses external JavaScript and CSS, loads docs via AJAX, renders markdown client-side through marked.js, and has breadcrumb navigation that tracks where you are in the folder structure. The portal’s goals section got reorganized into a real folder hierarchy. Dead sections got cut. AI and Dev Notes surfaces got added to the layout.

The practical bugs took longer than the architecture:

• UTF-8 handling required ADODB.Stream, because the simpler path was silently mangling characters.
• Windows backslash paths were breaking the URL routing. We found that the usual way, by loading a doc with a nested path and getting a 404 with no obvious cause.
• The host template’s CSS was bleeding into rendered doc content, so headings inside documents picked up styles from the surrounding admin chrome.

Each of these only surfaces in a real system, on real infrastructure, once someone actually opens the page.

The branch guard mattered more

While we were in the viewer, we added a PreToolUse hook to the Claude Code settings. This matters more than the docs work.

The hook runs before Edit or Write calls. It reads the current branch, compares it with the permitted branch conventions such as feature/ and hotfix/, and returns a one-line refusal on protected branches. master and develop are protected.

It belongs to the same family as the commit lock wrapper that coordinates repo access across sessions. The lock wrapper operates at commit time. The branch guard operates before the first file is touched. Earlier in the loop means cheaper to catch.

AI-assisted work changes the error mode. When a person was the only one editing files, a wrong-branch mistake cost a git checkout and a few minutes. When an AI-assisted session edits files, we might not notice the active branch until several changes have accumulated. A session can follow the stated task faithfully while the wrong branch is checked out, unless branch context is surfaced and constrained. The guard makes a repository constraint explicit at the point of action.

The task manager we talked ourselves out of

We also spent part of that afternoon on agent governance design. We talked ourselves into building a dedicated task manager to track agent work state outside JIRA, then talked ourselves back out of it. JIRA already has the fields we would build. Adding a parallel structure means two places to check and two places to drift. We pushed the impulse back into JIRA and kept moving. Not every internal-tooling itch should become a build.

What we had not said out loud yet

The message visibility fix was what we opened the session for. The docs viewer and the branch guard were what the day revealed we needed.

The docs viewer became important because we use the staff portal as a durable reference surface across AI-assisted sessions. A file dump makes orientation harder. A navigable, consistently rendered surface gives people and tools a clearer starting point, and the quality of that surface affects how much re-orientation the work requires.

The branch guard became load-bearing because we had been one careless session away from a bad edit on develop. We knew that in the back of our heads. We had not written it down as a constraint the system enforces.

Two things stay unresolved. A PreToolUse hook works cleanly in a single-agent session. Once multiple agents are editing across task branches at the same time, the enforcement model gets more complicated. Which session’s hook applies when two agents are open on the same repo? And does the rebuilt docs portal stay useful as goals, AI notes, and dev notes keep expanding? A better viewer is only a partial answer to the information-architecture problem.

Once AI starts helping you ship, internal docs and branch guardrails become part of the operating system around the product.

dxdev LESSON · paste into your AI coding agent
LESSON: Branch-Aware AI Guardrails
SOURCE: dxdev.com/blog/internal-docs-as-product
WHAT HAPPENED: An AI coding agent was editing files in a repo without any awareness of which branch it was on. When I was the only editor, a wrong-branch mistake cost a checkout and a few minutes. With an AI agent doing the edits, several commits could land on a protected branch before I noticed. The agent completes your stated intent on whatever branch is active, because it has no reason to care otherwise.
THE RULE: Enforce branch allowlists at the file-edit layer (before the first write), not just at commit time.
CHECK MY CODE, then report PASS / FAIL with file:line for each:
  1. Is there a pre-edit hook or guard that reads the current branch and blocks writes on protected branches (main, master, develop, or equivalent)?
  2. Does the allowlist use branch-prefix matching (e.g. feature/, hotfix/, chore/) rather than a flat list of exact names that silently misses new branch conventions?
  3. When a write is blocked, does the agent receive a clear one-line explanation of why so it does not silently retry or work around the guard?
THEN PRINT: a table (check, PASS/FAIL, evidence, fix) + a verdict (applies / partially / OUT_OF_SCOPE / no) + the single most important next action.