Platform Documentation, Sanitization, and Guarded Publishing

PROBLEM

The public site had become part of the platform.

The portfolio originally documented individual projects. As the lab expanded, those projects began depending on common infrastructure: Proxmox, OPNsense, Cloudflare, Guacamole, Kubernetes, DNS, isolated security ranges, and remote-management paths.

At that point, treating every page independently created two risks. First, an older page could describe an architecture that no longer matched reality. Second, troubleshooting examples and administrative screenshots could expose implementation details that added no value to the public documentation.

The goal of this phase was therefore not a visual redesign. The goal was to establish one current representation of the platform and a safer, repeatable way to publish changes.

CURRENT STATE

A dedicated platform page became the authoritative public overview.

A new Engineering Platform page was built around the actual current environment rather than around a theoretical end state. It records the physical host, virtualization layer, network roles, active workloads, remote-access architecture, storage limitations, known gaps, and roadmap.

Exact operational addressing and identifiers were intentionally excluded from the public representation. The architecture instead documents functions and trust relationships.

SANITIZATION

Useful architecture detail was separated from operational detail.

Earlier documentation included examples containing private addresses and direct implementation details. Those values were useful while troubleshooting, but they were not required for a public engineering explanation.

The sanitization pass replaced exact addressing with functional descriptions such as physical management network, firewall-routed internal lab network, target IP, and isolated security range.

ACCURACY

Deployed capabilities and planned capabilities were separated.

A documentation review also exposed a different class of problem: technologies used in another environment could be mistaken for capabilities deployed in the personal lab.

The platform documentation was therefore rewritten around a simple rule: current-state sections describe only what is actually deployed and validated. Future systems belong under known gaps or roadmap sections until they exist.

PUBLICATION WORKFLOW

Publishing became a guarded operation instead of a manual Git sequence.

Repeated site updates required the same sequence of checks and Git operations. Performing those steps manually created unnecessary opportunities to forget a validation step, publish from the wrong branch, or expose data that should have been generalized first.

A PowerShell publishing tool was added to the repository to perform the repetitive work consistently.

VALIDATION

The publisher blocks obvious disclosure before deployment.

The initial automation attempt exposed a compatibility issue in the PowerShell implementation: file objects were being piped directly into Select-String in a form that did not bind correctly in the local environment.

The workflow was simplified so the scan operates on resolved file paths. After that correction, the publisher completed an end-to-end run: repository validation passed, private-address scanning passed, credential scanning passed, current-state accuracy checks passed, the change was committed and pushed to the feature branch, main was fast-forwarded, and the working branch was restored automatically.

.\publish-site.ps1 `
  -CommitMessage "Bust platform stylesheet cache" `
  -MergeToMain

The successful second use of the tool was important because it validated the workflow against a real site change rather than merely validating the script that implemented the workflow.

DEPLOYMENT ISSUE

Local and production rendering diverged because the stylesheet was stale.

After the platform page was published, the local preview rendered correctly while the public page appeared to have reverted to an earlier visual state.

The repository contained the expected HTML and CSS, which narrowed the problem away from the source files. A versioned stylesheet reference was then used to force a fresh asset request during deployment.

<link rel="stylesheet" href="style.css?v=20260809-2">

After promotion, the public page matched the local version again. The incident reinforced that deployment validation needs to include the rendered production result, not only the repository state.

RESULT

The portfolio now has an operating model of its own.

The immediate result was a cleaner public architecture page, but the more important outcome was operational. Documentation now has an explicit current-state standard, public material is sanitized before deployment, and publication is handled through a repeatable guarded workflow.

LESSONS

Documentation is part of operating the platform.

Once a technical portfolio represents a live environment, documentation drift becomes an engineering problem. An inaccurate diagram can be as misleading as an inaccurate configuration file, and a troubleshooting example can expose information long after the original incident is resolved.

The useful pattern is the same one applied elsewhere in infrastructure: define an intended state, validate before promotion, automate repetitive checks, and make the safer path the easier path.

NEXT

The documentation now waits on real engineering work.

The next journal entries should come from implemented platform changes, not additional website refinement. Physical network segmentation, management-plane changes, Proxmox automation, and further Kubernetes operating-model work will be documented after each capability is implemented and validated.