docs: harden TalkEd repo guidance and hygiene checks

.github/labels.md

@@ -0,0 +1,20 @@
+# Repository Labels
+
+This repository currently uses the default GitHub label baseline:
+
+- `bug`
+- `documentation`
+- `duplicate`
+- `enhancement`
+- `good first issue`
+- `help wanted`
+- `invalid`
+- `question`
+- `wontfix`
+
+## Governance Notes
+
+- These labels were confirmed via `gh label list` on 2026-05-27.
+- If labels change in the GitHub UI, update this file in the same change so the tracked baseline stays in sync.
+- GitHub branch protection is not currently available for this private repository tier. The GitHub API returns `403 Upgrade to GitHub Pro or make this repository public` when querying branch-protection settings for `main`.
+- Until that changes, repository discipline depends on review, CI, and explicit git staging rather than platform-enforced protection rules.

.github/workflows/repo-hygiene.yml

@@ -0,0 +1,52 @@
+name: Repository Hygiene
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  hygiene:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Lint markdown
+        run: npx --yes markdownlint-cli@0.45.0 "**/*.md" --ignore node_modules
+
+      - name: Validate JSON files
+        run: |
+          set -e
+          # jq and ruby are provided by the ubuntu-latest runner image.
+          while IFS= read -r -d '' file; do
+            jq empty "$file"
+          done < <(find . -path './.git' -prune -o -name '*.json' -print0)
+
+      - name: Validate YAML files
+        run: |
+          set -e
+          # jq and ruby are provided by the ubuntu-latest runner image.
+          while IFS= read -r -d '' file; do
+            ruby -e 'require "yaml"; YAML.load_file(ARGV[0])' "$file"
+          done < <(find . -path './.git' -prune -o \( -name '*.yml' -o -name '*.yaml' \) -print0)
+
+      - name: Verify ignored UI and resource patterns
+        shell: bash
+        run: |
+          set -e
+          # This step relies on Bash 4+ array syntax available on ubuntu-latest.
+          samples=(sample.dfm sample.res sample.ico sample.dcu TalkEd.exe)
+          expected=${#samples[@]}
+          actual=$(printf '%s\n' "${samples[@]}" | (git check-ignore --stdin || true) | wc -l)
+          if [ "$actual" -ne "$expected" ]; then
+            echo "Expected $expected ignored artifact matches, found $actual"
+            exit 1
+          fi

.markdownlint.json

@@ -0,0 +1,4 @@
+{
+  "default": true,
+  "MD013": false
+}

BUILDING.md

@@ -5,9 +5,9 @@
 TalkEd is a classic Delphi 7 VCL application. The authoritative source build surface is:
 
 - project file: `TLKEdit.dpr`
-- compiler options: `TLKEdit.cfg`
+- local compiler options file: `TLKEdit.cfg` when present in a native Delphi worktree
 - IDE project options: `TLKEdit.dof`
-- Windows resource file: `TLKEdit.res`
+- local Windows resource file: `TLKEdit.res` when present in a native Delphi worktree
 
 ## What Works Today
 
@@ -21,6 +21,14 @@ Expected flow:
 2. Ensure the companion units and forms are present in the same repository root.
 3. Build the project to produce `TalkEd.exe`.
 
+Note that some native Delphi companion files are intentionally untracked in git. A Windows build environment may still need locally generated or locally maintained files such as `TLKEdit.cfg`, `TLKEdit.res`, `.dfm`, and icon resources.
+
+If one of those files is missing:
+
+1. let Delphi regenerate `TLKEdit.cfg` from the project when possible,
+2. regenerate `TLKEdit.res` from the IDE project resource settings or copy it from a known-good Windows worktree,
+3. stop and recover missing `.dfm` or other form/resource files from a trusted historical checkout rather than recreating them by guesswork.
+
 ### Command-Line Build
 
 The VS Code task surface assumes a Delphi command-line compiler such as `dcc32.exe` on Windows.
@@ -42,17 +50,14 @@ The VS Code launch surface includes:
 
 ## What Does Not Exist Yet
 
-- No modern CI pipeline.
 - No repeatable non-Windows source build.
 - No FPC/Lazarus project file checked into this repository.
 - No automated packaging step.
 
 ## Important Files for Build Success
 
 - `TLKEdit.dpr`
-- `TLKEdit.cfg`
 - `TLKEdit.dof`
-- `TLKEdit.res`
 - `UMainForm.pas`
 - `UTLKFile.pas`
 - `USearchForm.pas`
@@ -63,7 +68,7 @@ The VS Code launch surface includes:
 
 ## Compiler Notes
 
-`TLKEdit.cfg` shows this project was configured with Delphi-era compiler directives and paths. Those settings should be treated as historical build inputs rather than modernized defaults.
+If a local `TLKEdit.cfg` file is present, it reflects Delphi-era compiler directives and machine-specific paths. Treat it as a local historical build input rather than a portable repository contract.
 
 In particular:
 
@@ -95,3 +100,5 @@ The repository ships workspace tasks for:
 - launching the built executable.
 
 These tasks are convenience tooling only. They do not replace real runtime verification against TLK files.
+
+The repository also ships a GitHub Actions workflow for markdown, JSON, YAML, and ignore-policy hygiene. That workflow is a repository-health check, not a Delphi build.

CONTRIBUTING.md

@@ -30,6 +30,10 @@ This repository contains the classic Delphi 7 TalkEd source tree and workspace s
 
 Non-Windows environments are suitable for workspace maintenance, documentation, and launch-flow validation, but not authoritative source compilation.
 
+Branch protection is not currently available for this private repository tier. Contributors should therefore treat PR review, CI status, and careful staging as the practical enforcement layer.
+That also means accidental direct pushes are easier than they should be on a protected repository. Prefer feature branches and PR-based review even for small changes, and double-check CI status before merging.
+If a direct push to `main` happens by mistake, do not rewrite history casually. Notify the other contributors, open a follow-up corrective PR if needed, and prefer an explicit revert or fix-forward commit over a force-push.
+
 ## Contribution Priorities
 
 Prioritize changes in this order:
@@ -84,6 +88,7 @@ If the change touches ignored files such as `.dfm`, `.res`, or `.ico`, call that
 The current repository policy ignores several Delphi-era binary or designer artifacts, including:
 
 - `.dcu`
+- `.cfg`
 - `.dfm`
 - `.ddp`
 - `.res`
@@ -93,10 +98,12 @@ The current repository policy ignores several Delphi-era binary or designer arti
 That means:
 
 - pure form-designer changes may not show up in git status,
+- local compiler-option files may exist on disk without being committed,
 - resource or icon changes are not tracked automatically,
 - a contributor may need a deliberate repository policy change before certain visual updates can be reviewed properly.
 
 Do not silently rely on ignored artifacts for a functional fix.
+Do not rely on untracked local compiler settings for reproducible build guidance either; if a setting matters to future contributors, document it in tracked markdown rather than assuming a local `TLKEdit.cfg` will be present.
 
 ## Code Review Expectations
 

CONVENTIONS.md

@@ -25,6 +25,14 @@ Ignored by current policy include:
 
 When making a change that depends on one of those files, document the limitation instead of pretending it is tracked.
 
+`TLKEdit.cfg` is intentionally ignored because the local file in a Delphi environment can contain machine-specific paths. Repository docs should describe it as a local companion file, not as a guaranteed tracked artifact.
+If a local compiler or library setting matters to reproducible work, capture that requirement in tracked documentation instead of assuming contributors will share the same untracked `TLKEdit.cfg` contents.
+When such a setting matters, use this checklist:
+
+1. add the requirement to `BUILDING.md` or `CONTRIBUTING.md`,
+2. mention it in the PR summary or change notes for the affected work,
+3. avoid copying machine-specific absolute paths or user-specific IDE state into tracked files.
+
 ## Naming Conventions
 
 ### Units
@@ -89,6 +97,13 @@ When editing one of those units, preserve the header style. If you add meaningfu
 - Build tasks should point at `TLKEdit.dpr`.
 - Launch tasks should assume `TalkEd.exe` and optional `.tlk` startup arguments.
 - Non-Windows launch support is convenience tooling via Wine, not a statement of native build parity.
+- GitHub Actions checks should stay repository-portable and must not imply Delphi source-build support where none exists.
+
+## Repository Governance
+
+- Default GitHub labels may be configured and documented in tracked repo files.
+- Do not claim branch protection is enabled unless the GitHub API confirms it.
+- For this repository at present, branch protection should be documented as blocked by repository plan limits rather than represented as active policy.
 
 ## Change Discipline
 

README.md

@@ -2,6 +2,8 @@
 
 TalkEd is a Delphi 7 desktop editor for BioWare-style `TLK V3.0` talk table files. In practice, this repository is aimed at Knights of the Old Republic modding workflows where a `.tlk` file acts as a string database keyed by `StrRef` values.
 
+This is the **authentic** source code Stoffe was working with 10-20 years ago, released to the community so it can be maintained and kept from becoming abandonware.
+
 The application lets you:
 
 - open an existing `.tlk` file from the UI or from the command line,
@@ -26,7 +28,7 @@ The application lets you:
 Top-level files are intentionally flat and mirror the original Delphi 7 project structure.
 
 - `TLKEdit.dpr`: VCL application entrypoint and startup wiring.
-- `TLKEdit.cfg`: compiler switches used by the Delphi command-line build.
+- `TLKEdit.cfg`: local Delphi compiler options file that may exist in a native build environment but is intentionally not tracked in git.
 - `TLKEdit.dof`: Delphi IDE project options.
 - `UTLKFile.pas`: TLK parsing, in-memory string storage, and save logic.
 - `UMainForm.pas`: main window, menus, grid display, and orchestration.
@@ -115,6 +117,8 @@ The repository does not contain an automated cross-platform build. On Linux and
 
 See `BUILDING.md` for the full build and launch workflow.
 
+Local Delphi companion files such as `TLKEdit.cfg`, `.dfm`, `.res`, and icon resources may exist in a native Windows worktree, but this repository intentionally does not commit those UI/resource artifacts today.
+
 ## Current Workspace Support
 
 The `.vscode` folder is tuned to this repository and includes:
@@ -131,6 +135,8 @@ The `.vscode` folder is tuned to this repository and includes:
 - Build validation is currently manual and environment-dependent.
 - The repository `.gitignore` excludes `.dfm`, `.res`, `.ico`, `.ddp`, and generated binaries, which means some visual/resource changes are not tracked unless that policy is changed intentionally.
 - The TLK reader/writer explicitly carries fixes for long strings beyond the original 4096-byte buffer behavior, but this remains an area worth validating when changing TLK serialization.
+- GitHub branch protection is not currently enforceable on this private repository tier; the GitHub API returns `403 Upgrade to GitHub Pro or make this repository public` for that setting.
+- Contributor workflow expectations for that limitation live in `CONTRIBUTING.md`.
 
 ## Documentation Map
 
@@ -139,6 +145,7 @@ The `.vscode` folder is tuned to this repository and includes:
 - `ARCHITECTURE.md`: unit and workflow breakdown.
 - `CONTRIBUTING.md`: contribution process and validation expectations.
 - `CONVENTIONS.md`: coding and repository conventions specific to this project.
+- `.github/labels.md`: current repository label baseline and governance notes.
 
 ## Repository Remote
 

docs/plans/2026-05-27-repo-hardening-plan.md

@@ -0,0 +1,150 @@
+---
+title: TalkEd Repo Hardening Plan
+date: 2026-05-27
+status: active
+---
+
+## Overview
+
+## Problem Frame
+
+The repository bootstrap landed source, docs, and VS Code support, but it still has three gaps that affect maintainability and team workflow:
+
+1. Source-vs-repo parity is imperfect because repository docs still talk about some local Delphi companion artifacts as if they are committed, while the current ignore policy intentionally excludes several of them.
+2. The repository has no CI guardrail for markdown, JSON, YAML, or ignore-policy drift.
+3. Governance hardening is incomplete: default labels exist, but branch protection cannot currently be enabled on this private repository because GitHub returns a 403 for this feature tier.
+
+## Scope Boundaries
+
+In scope:
+
+- Make the repository docs accurately reflect tracked versus intentionally ignored Delphi-era artifacts.
+- Add lightweight GitHub Actions checks that are valid for this repository without requiring Delphi builds.
+- Add a small amount of repository governance metadata where it is clearly useful and low-risk.
+- Document the branch-protection platform limitation rather than pretending it is configured.
+
+Out of scope:
+
+- Native Delphi build automation.
+- Tracking `.dfm`, `.res`, `.ico`, `.dcu`, or built executables.
+- Reworking the Pascal source structure.
+- UI or resource-file changes.
+
+## Key Technical Decisions
+
+- Keep the current policy of excluding UI/resource artifacts from git. This matches the explicit user instruction for this session.
+- Treat `TLKEdit.cfg` as a local build artifact rather than a committed source file. The existing file contains machine-specific paths, so documentation should describe it as a local companion file rather than as a guaranteed tracked file.
+- Use GitHub Actions only for repository-hygiene checks that do not depend on Delphi toolchains.
+- Treat branch protection as a documented external blocker because the GitHub API returns `403 Upgrade to GitHub Pro or make this repository public` for this repository.
+
+## Implementation Units
+
+### U1: Align docs with tracked-artifact reality
+
+Goal:
+Make repository-facing docs accurately describe which Delphi files are committed, which are local-only, and which are intentionally ignored.
+
+Files:
+
+- Modify `README.md`
+- Modify `BUILDING.md`
+- Modify `CONTRIBUTING.md`
+- Modify `CONVENTIONS.md`
+
+Approach:
+
+- Remove or reword any implication that `TLKEdit.cfg`, `.dfm`, `.res`, `.ico`, or similar ignored artifacts are part of the committed repository surface.
+- Clarify that some files may be required locally for native Delphi work even when they are intentionally absent from git.
+- Add a short note about branch-protection unavailability in the governance-facing docs if helpful.
+
+Patterns to follow:
+
+- Keep the same concise, repository-grounded style already established in the new markdown files.
+
+Test scenarios:
+
+- Happy path: all updated docs read consistently and no section contradicts the ignore policy.
+- Edge case: docs distinguish “exists locally” from “committed to repo”.
+- Error path: no markdown lint regressions.
+
+Verification:
+
+- Markdown diagnostics clean for touched files.
+
+### U2: Add repository-hygiene CI
+
+Goal:
+Add a GitHub Actions workflow that validates repository-health artifacts that are portable across environments.
+
+Files:
+
+- Create `.github/workflows/repo-hygiene.yml`
+
+Approach:
+
+- Run markdown lint across repository docs.
+- Validate JSON files parse.
+- Validate YAML files parse.
+- Assert representative UI/resource artifact names still match the intended ignore policy.
+
+Patterns to follow:
+
+- Keep workflow simple, dependency-light, and independent from Delphi toolchains.
+
+Test scenarios:
+
+- Happy path: workflow file parses and targets push/pull_request.
+- Edge case: ignore-policy check uses path patterns that do not require the ignored files to exist in CI.
+- Error path: malformed markdown/json/yaml would fail deterministically.
+
+Verification:
+
+- YAML diagnostics clean.
+- Review workflow contents for deterministic failure signals.
+
+### U3: Add minimal governance metadata
+
+Goal:
+Capture the remaining governance state in tracked repo files so collaborators understand what is configured and what is blocked externally.
+
+Files:
+
+- Create `.github/labels.md`
+- Optionally modify `README.md` or `CONTRIBUTING.md` if cross-references are useful
+
+Approach:
+
+- Record the working default-label set observed via `gh label list`.
+- Record that branch protection is currently blocked by GitHub plan limits on this private repo.
+- Avoid fake configuration files that imply protections are active when they are not.
+
+Patterns to follow:
+
+- Prefer factual, operational documentation over speculative governance prose.
+
+Test scenarios:
+
+- Happy path: governance doc states current label baseline and branch-protection blocker clearly.
+- Edge case: wording does not imply branch protection has been enabled.
+- Error path: markdown diagnostics remain clean.
+
+Verification:
+
+- Markdown diagnostics clean for touched files.
+
+## Dependencies and Sequence
+
+1. U1 first so the docs reflect the actual repository state before adding new automation.
+2. U2 second because CI should validate the corrected docs and metadata.
+3. U3 last so the governance note reflects the final repository-hygiene setup and current GitHub platform constraint.
+
+## Risks
+
+- Overstating what is committed versus what exists locally would recreate the current parity problem.
+- A CI workflow that depends on unavailable tooling would become noise instead of a guardrail.
+- Governance documentation could accidentally imply that branch protection is configured when it is not.
+
+## Deferred To Implementation
+
+- Choose the simplest workflow dependencies available on `ubuntu-latest` without adding repository package manifests just for linting.
+- Decide whether the governance note belongs best in a dedicated `.github/labels.md` file or in existing docs after reading the final markdown edits together.