Skip to content

Add initial user-facing docs#600

Open
mariusvniekerk wants to merge 8 commits into
mainfrom
docs/initial-user-facing-docs
Open

Add initial user-facing docs#600
mariusvniekerk wants to merge 8 commits into
mainfrom
docs/initial-user-facing-docs

Conversation

@mariusvniekerk

@mariusvniekerk mariusvniekerk commented Jun 26, 2026

Copy link
Copy Markdown
Collaborator
  • Add a Zensical-backed public docs tree for quickstart, configuration, commands, troubleshooting, and workflows.
  • Add issue triager and code reviewer walkthroughs focused on the UI workflows maintainers use day to day.
  • Include e2e-backed light and dark workflow screenshots generated from the sample backend.

@mariusvniekerk mariusvniekerk force-pushed the docs/initial-user-facing-docs branch from 55a68f1 to d7e89f4 Compare June 26, 2026 22:00
@roborev-ci

roborev-ci Bot commented Jun 26, 2026

Copy link
Copy Markdown

roborev: Combined Review (d7e89f4)

Docs are mostly clean, but one medium-severity command example issue should be fixed before merge.

Medium

  • docs/commands.md:45, docs/configuration.md:139, docs/troubleshooting.md:76
    • The docs show middleman docs add-folder ~/docs --name Docs, but runDocsAddFolder uses Go's flag package with usage [flags] <path>. Flags after the path are treated as extra positional args, so the documented command fails.
    • Fix by putting flags before the path, for example: 
      middleman docs add-folder --name Docs ~/docs

Panel: ci_default_security | Synthesis: codex, 6s | Members: codex_default (codex/default, done, 5m13s), codex_security (codex/security, done, 1m56s) | Total: 7m15s

@mariusvniekerk @codex
docs: add initial user-facing docs
e476b5f 
middleman had implementation notes but no concise user-facing documentation for setup, operation, and maintainer workflows. Add the initial public docs tree with Zensical configuration, quickstart/configuration/commands/troubleshooting pages, and role-oriented issue triage and code review walkthroughs.

The workflow captures are generated from the real seeded e2e backend in light and dark mode as actual standalone SVG DOM/CSS output. The generator preserves computed theme tokens for dark SVGs and waits for sync UI to idle before capture, so the docs do not show transient spinners or carry embedded raster screenshots.

Validation: node frontend/node_modules/.bin/playwright test --config docs/screenshots/playwright.config.ts --project=chromium; standalone Chromium render check for both dark SVGs; rg -n '<image|data:image|base64|\.png|\.jpe?g|>\s*Syncing|>\s*syncing(?:…|\s*\()|aria-label="Syncing"|title="Syncing"' docs/assets/generated docs/screenshots returned no matches; go test ./internal/testutil -shuffle=on; git diff --cached --check; scripts/context-sync --check.

Generated with Codex
Co-authored-by: Codex <codex@openai.com>
@mariusvniekerk mariusvniekerk force-pushed the docs/initial-user-facing-docs branch from d7e89f4 to e476b5f Compare June 27, 2026 15:06
@roborev-ci

roborev-ci Bot commented Jun 27, 2026

Copy link
Copy Markdown

roborev: Combined Review (e476b5f)

Medium-risk doc issues need fixing before merge; no security regressions were found.

Medium

  • docs/commands.md:45
    The docs add-folder examples place flags after the positional path, but Go’s flag parser stops at the first positional argument. These commands will be parsed as extra args and fail. The same issue appears in docs/configuration.md and docs/troubleshooting.md.

    Fix: Move flags before the path, for example:

    middleman docs add-folder --name Docs ~/docs
middleman docs add-folder --id project --daemon kata-main ~/project-docs

  • docs/configuration.md:19
    The sample config sets data_dir = "~/.config/middleman", but config loading does not tilde-expand data_dir. Copying this example would store state under a literal relative ~/.config/middleman path.

    Fix: Omit data_dir for the default, or show an absolute path and mention MIDDLEMAN_HOME for relocating both config and data.

Panel: ci_default_security | Synthesis: codex, 9s | Members: codex_default (codex/default, done, 6m19s), codex_security (codex/security, done, 2m41s) | Total: 9m9s

@mariusvniekerk
docs: fix copyable docs configuration examples
f478188 
The docs mode examples used flag placement that Go's flag parser treats as positional arguments, so copying them could fail instead of registering a folder. The sample config also suggested a tilde data_dir value that the loader does not expand, risking state in an unexpected relative path.

Validation: rg -n "docs add-folder [^\n]*~[^\n]*--|data_dir = \"~" docs; go test ./cmd/middleman -run 'TestDocs|TestRunDocs' -shuffle=on; git diff --check\n\nGenerated with Codex\nCo-authored-by: Codex <codex@openai.com>
@roborev-ci

roborev-ci Bot commented Jun 30, 2026

Copy link
Copy Markdown

roborev: Combined Review (f478188)

Summary verdict: one medium documentation issue should be fixed before merge.

Medium

  • docs/quickstart.md:12 - The quick start uses https://github.com/wesm/middleman.git, but the canonical repository is kenn-io/middleman. Users following the setup docs may clone the wrong project or hit a stale/unavailable namespace.
    • Fix: change the clone URL to https://github.com/kenn-io/middleman.git.

Panel: ci_default_security | Synthesis: codex, 6s | Members: codex_default (codex/default, done, 7m43s), codex_security (codex/security, done, 2m37s) | Total: 10m26s

@mariusvniekerk @codex
docs: point setup instructions at canonical repo
1110b51 
The public setup docs still cloned the old wesm namespace even though this project now lives under kenn-io. Users copying those commands could land on the wrong repository or a stale namespace before they ever build middleman.

Validation: rg -n "git clone https://github.com/wesm/middleman.git" README.md docs/*.md docs/zensical.toml; rg -n "git clone https://github.com/kenn-io/middleman.git" README.md docs/*.md; git diff --check

Generated with Codex
Co-authored-by: Codex <codex@openai.com>
@roborev-ci

roborev-ci Bot commented Jun 30, 2026

Copy link
Copy Markdown

roborev: Combined Review (1110b51)

Medium-risk issue found in the screenshot regeneration path; no security issues identified.

Medium

  • docs/screenshots/docs-screenshots.spec.ts:1
    The screenshot generator hardcodes Playwright imports under ../../frontend/node_modules/..., and the documented command uses frontend/node_modules/.bin/playwright. In this Bun workspace setup, dependencies are not guaranteed to exist at that nested path after a clean install, so the documented screenshot regeneration flow can fail before Playwright starts.
    Fix: Import @playwright/test normally and invoke Playwright from a workspace/script where it is declared, or add a root-level script/devDependency and document that command instead of hardcoding frontend/node_modules.

Panel: ci_default_security | Synthesis: codex, 7s | Members: codex_default (codex/default, done, 5m51s), codex_security (codex/security, done, 2m18s) | Total: 8m16s

@mariusvniekerk @codex
docs: make screenshot regeneration use root Playwright
4dfc801 
The docs screenshot task imported and executed Playwright through frontend/node_modules, which is not a stable path in a clean Bun workspace. Make the regeneration path resolve from the root package that declares Playwright, and add a regression guard so the command does not drift back to nested node_modules assumptions.

Validation: node --test scripts/docs-screenshots-command.test.mjs failed before the fix with missing docs:screenshots script; make script-tests; make playwright-version-check; node node_modules/vite-plus/bin/vp run docs:screenshots --list; node node_modules/vite-plus/bin/vp run docs:screenshots; git diff --check

Generated with Codex
Co-authored-by: Codex <codex@openai.com>
@roborev-ci

roborev-ci Bot commented Jun 30, 2026

Copy link
Copy Markdown

roborev: Combined Review (4dfc801)

No issues found.

Panel: ci_default_security | Synthesis: codex | Members: codex_default (codex/default, done, 9m3s), codex_security (codex/security, done, 2m59s) | Total: 12m2s

mariusvniekerk and others added 4 commits June 30, 2026 16:15
@mariusvniekerk @codex
fix: keep docs screenshots on current Playwright
dbcd64d 
The docs screenshot workflow added a root Playwright dependency, but the branch was based before main moved the frontend workspaces and CI Playwright image to 1.61.0. GitHub Actions runs the PR merge commit, where that stale root pin made the guardrail report conflicting Playwright versions.

Keep the root screenshot runner, workspace Playwright pins, and CI browser image comments on the same version so local hooks and the PR merge tree enforce one browser toolchain.

Validation: make script-tests; make playwright-version-check; applied the initial root-pin diff to a temporary archive of the PR merge tree and ran scripts/check-playwright-version.mjs successfully; git diff --check

Generated with Codex
Co-authored-by: Codex <codex@openai.com>
@mariusvniekerk @codex
docs: address docs review traps
8062ee9 
Roborev flagged a few user-facing setup and maintenance traps in the initial docs work. Keep the dirty-migration guidance from telling users to discard the only copy of local-only state, restore the synthetic-example privacy rule, and make the docs screenshot command regression test execute the cheap --list path instead of only checking strings.

Validation: make script-tests; git diff --check

Generated with Codex
Co-authored-by: Codex <codex@openai.com>
@mariusvniekerk @codex
merge: sync main into docs branch
73a6f92 
Bring current main into the docs branch so the PR merge tree no longer conflicts in the package manifests and lockfile after the Playwright pin fix. The merge keeps the docs screenshot root Playwright dependency while taking main's newer frontend package metadata.

Validation: make script-tests; make playwright-version-check; git diff --cached --check

Generated with Codex
Co-authored-by: Codex <codex@openai.com>
@mariusvniekerk @codex
docs: clarify dirty database recovery
ca3aece 
Roborev pointed out that telling users to copy or rename the dirty database was ambiguous: copying alone leaves the bad database in place, so startup would retry the same failed migration. Make the recovery sequence explicit by backing up first, then moving the database and SQLite sidecars out of the data directory before restart.

Validation: git diff --check

Generated with Codex
Co-authored-by: Codex <codex@openai.com>
@roborev-ci

roborev-ci Bot commented Jun 30, 2026

Copy link
Copy Markdown

roborev: Combined Review (ca3aece)

Medium finding: workflow screenshots will 404 in the built docs.

Medium

  • docs/workflows/code-reviewer.md:7, docs/workflows/issue-triager.md:7
    The workflow pages embed screenshots with raw HTML src="../assets/...", but docs/zensical.toml has use_directory_urls = true. In the built site, /workflows/code-reviewer/ resolves that relative path to /workflows/assets/..., so the screenshots will 404.

    Suggested fix: use paths that resolve correctly from the built directory URL, or switch to Markdown image syntax or another docs-supported mechanism that rewrites asset paths correctly.

Panel: ci_default_security | Synthesis: codex, 7s | Members: codex_default (codex/default, done, 6m54s), codex_security (codex/security, done, 2m21s) | Total: 9m22s

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@mariusvniekerk