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.

Audit offer Portfolio narrative Portfolio spine roadmap Operational foundation Cloud delivery readiness Preview performance Local AI baseline Rollback readiness AI agent authority Identity security Public-safe workflow

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 is a public-safe documentation note. It does not include private operational material, customer evidence or account-specific recovery material.

Initial problem

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

However, a stale Vercel project was still connected to the repository and attempted to build it as a Next.js project. The failure indicated that no Next.js version was detected.

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 setup was added with a dedicated Vercel build script.

A Vercel configuration file was added to point Vercel to the static build output.

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. Documented troubleshooting as evidence

The Vercel-related troubleshooting was documented as a public-safe operational documentation case.

The important finding was that the local documentation build approach worked, while the remaining deployment problem belonged to the wrong Vercel project boundary.

The documentation intentionally avoided account-specific operational values.

7. Documented recovery-material handling

A separate handling note was created for account recovery material.

The rule is simple:

Document the handling process.
Never store the private material itself.

8. Removed the stale Vercel project boundary issue

The old 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.

The stale 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 issue was not only fixed or documented.

It became an example 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:

The list above is a boundary example for what must not be claimed.

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.