Documentation · Governance · Evidence

Deployment Recovery Summary 2026-06-23

Selected public-safe documentation pages from a private technical documentation hub. The focus is documented, controlled and reviewable technical delivery.

Portfolio narrative Cybersecurity perspective AI agent boundaries Identity security

Technical Documentation Deployment Recovery Summary — 2026-06-23

Purpose

This document summarizes the work done on 2026-06-23 to turn the technical documentation repository into a working public-safe static documentation preview and to clean up the deployment boundary around Vercel.

The purpose is to preserve the reasoning, changes and benefits of the work so the repository history is understandable later.

Scope

This summary covers:

This summary does not include secrets, API keys, recovery codes, customer evidence, payment details or private operational material.

Initial problem

The repository was intended to be a technical documentation hub, not a Next.js application.

However, a Vercel project named nextjs-boilerplate was still connected to the repository and attempted to build it as a Next.js project. The failure looked like this in the deployment logs:

No Next.js version detected.
Make sure your package.json has "next" in either "dependencies" or "devDependencies".

The correct interpretation was:

This was not a missing Next.js dependency problem.
This was a wrong Vercel project / framework preset problem.

Adding Next.js would have made the repository heavier and less aligned with its purpose.

Actions taken

1. Added a static Vercel build path

A minimal package.json was added with a dedicated Vercel build script:

{
  "scripts": {
    "vercel-build": "node tools/build-vercel-static-site.mjs"
  }
}

A vercel.json file was added to point Vercel to the static build output:

{
  "buildCommand": "npm run vercel-build",
  "outputDirectory": "public"
}

2. Added a minimal static documentation generator

A dependency-light Node script was added:

tools/build-vercel-static-site.mjs

It generates:

This kept the repository lightweight and avoided unnecessary framework complexity.

3. Improved Markdown table rendering

The first static preview worked, but Markdown tables rendered as raw pipe syntax.

The generator was improved to detect Markdown table rows and render them as HTML tables with basic responsive styling.

This improved readability for:

4. Added public static preview boundary documentation

A new boundary document was added:

docs/PUBLIC_STATIC_PREVIEW_BOUNDARY.md

It clarifies that:

5. Clarified README wording

The README was updated so it no longer describes the published preview simply as a private hub.

The current distinction is:

Repository = private working hub
Vercel site = public-safe static preview of selected documentation pages

6. Added Vercel AI Gateway troubleshooting documentation

The Vercel AI Gateway local text-generation test was documented as a public-safe troubleshooting case.

The important finding was that the local Node/TypeScript setup and .env.local loading worked, but Vercel AI Gateway blocked generation because the account required valid credit-card verification.

The documentation intentionally avoided storing the actual API key.

7. Documented Vercel recovery-code handling

A separate note was added for Vercel recovery-code handling.

The rule is simple:

Document the recovery-code handling process.
Never store the recovery codes themselves.

8. Removed the stale Vercel project boundary issue

The old nextjs-boilerplate Vercel project was identified as the remaining source of failing deployment status.

The correct fix was to remove or disconnect the stale Vercel project, not to change the documentation repository into a Next.js application.

Final state

The correct Vercel deployments for the documentation hub reached a successful state:

Vercel – technical-documentation: success
Vercel – technical-documentation-8mup: success

The stale nextjs-boilerplate deployment path was treated as a separate cleanup item and not as a valid signal about the documentation repository itself.

Benefits

1. The repository is now demonstrable

The repository is no longer only a private Markdown collection.

It now has a public-safe static preview that can be linked from a GitHub profile, portfolio or job application.

2. The portfolio narrative is easier to understand

The static preview helps explain that the portfolio is not a random collection of repositories.

The common theme is:

documented, controlled and reviewable technical delivery

3. The work shows operational judgment

The correct solution was not to add unnecessary Next.js complexity.

The better solution was:

right control, right layer, right weight

A static documentation hub needed a static documentation preview, not a full application framework.

4. The public/private boundary is clearer

The work improved the distinction between:

This is directly relevant to regulated IT, DevSecOps, documentation governance and operational security work.

5. The troubleshooting itself became evidence

The Vercel and AI Gateway issues were not only fixed or documented.

They became examples of:

What this proves

This work demonstrates practical documentation and operational maturity:

It should be framed as documentation-driven operational governance work, not as a full production documentation platform.

What not to claim

Do not claim that this work proves:

Use calibrated wording:

I built a lightweight public-safe static documentation preview for a private technical documentation hub, with clear public/private boundaries and deployable portfolio evidence.

Follow-up items

Potential future improvements:

Final summary

The work converted the repository from a private documentation collection into a controlled documentation hub with a public-safe static preview.

The main value was not the Vercel deployment itself. The main value was proving that technical documentation can be made visible, reviewable and useful without leaking private material or adding unnecessary platform complexity.