​

T3Planet Docs — Agent Context

​

Who we write for (client / audience model)

​

Editorial tone (match T3Planet client expectations)

• Direct and accurate — no filler, no “AI slop”, no marketing fluff in technical steps.
• Do not patronize — omit obvious navigation like “Open TYPO3 → click module → select page in tree” unless the page is explicitly Getting started for non-TYPO3 users.
• Prefer Supademos + concise prose over duplicate full-page screenshots when both show the same UI.
• Use product names customers see — e.g. AI Foundation, AI Accessibility (not only internal slugs like “T3AF” in customer-facing intro text; extension keys in backticks are fine).
• Preserve legal/privacy nuance — DPA/GDPR pages describe capabilities and options, not over-claiming compliance.
• Links must work on live — host-at prefix /en/latest, full paths under product folders (see Link conventions).

​

How to prepare and write content (client feedback lessons)

​

Content structure that works

​

Voice rules from feedback (do / don’t)

• Write complete sentences. Never ship truncated frontmatter description (live meta shows the cut-off — e.g. “…voiceover, s”).
• Separate license vs AI provider: put provider requirements in feature/setup prose; keep Important notes focused (e.g. “valid T3AA license required”) when the client says provider wording there misleads.
• Prefer concrete verbs: “Open an issue from the results list to continue in Fix Hub” over taglines.
• Match product reality. If Scanner/Lighthouse run both desktop and mobile, do not document “Choose Desktop or Mobile”.
• For settings sentences, prefer clear subjects: Settings are saved per site in config.yaml. It does not change page content in the database. (client-approved shape).
• After local edits: purge LAN preview cache (curl -s http://127.0.0.1:3000/__t3_cache_purge) and give the LAN URL (http://<LAN>:3000/...).

• Slogan / poster lines the client rejects, e.g. “A scan reports findings. Fix Hub is where work happens.”
• Over-explain negatives the client then removes (e.g. repeated “Lighthouse is not in Fix Hub” / “Fix Hub does not run the scan itself”) unless they asked for that clarification.
• Generic “How to open it” for TYPO3-experienced readers.
• Leave empty headings (## Module overview with no body).
• Invalid Lucide icons (sliders, text) — use sliders-horizontal, type, etc.
• RST leftovers (::, .. code-block::) on live-facing pages.
• Short links (/en/latest/FixHub/Index) or double host-at (/en/latest/en/latest/...).

​

Feedback loop (how the client works)

1. They browse local LAN preview or paste a live URL + screenshot / purple box.
2. They ask for a precise edit (remove line X, rewrite sentence Y, add table Z).
3. Expect local-first; deploy only when they say push / live / Markus.
4. When they say “train yourself / improve context.md” — update this file and .cursor/rules/ in the same turn.

​

T3AA product facts agents must not contradict

• Fix Hub displays/manages Scanner findings only (not Lighthouse). Lighthouse stays under Scanner → Lighthouse.
• Bulk Scans queues pages for the Scanner engine + Scheduler/CLI (nst3aa:monitor:run).
• AI generation (alt text, audio, voiceover, simplify) needs AI Foundation provider/features; inventory/review alone may not call AI.
• Extension code (when fixing product behaviour) may live under TYPO3 setups, e.g. …/packages/ns_t3aa — docs repo alone cannot “fix” Fix Hub backend without that package.

​

How this client typically works with agents

​

Always clarify: local vs live

• Local = files in this workspace; preview via :3000 (LAN/fast proxy) or :3001 (raw mint).
• Live = https://docs.t3planet.de/en/latest after Mintlify deploy from markus remote.

​

Project identity

​

CRITICAL: which GitHub repo Mintlify deploys from

​

Remotes

origin  https://github.com/nitsan-technologies/T3Planet-docs.git   # org / official mirror
markus  https://github.com/markus-neumannn/T3Planet-docs.git      # Mintlify LIVE source

​

Deployment rule

1. git push markus HEAD:master is required for live updates (while Git settings stay on the fork).
2. git push origin HEAD:master syncs org repo; does not replace step 1 for live.
3. Never force-push unless explicitly authorized.
4. If live is stale after pushing origin only → push markus (incident 2026-09-16).

​

Verify live deploy (evidence-based)

• Feature Guide: sliders-horizontal / type icons present (not broken sliders / text).
• Dashboard: no dashboard-overview.webp in page when removed.
• Bulk Scans: bash fence for vendor/bin/typo3 nst3aa:monitor:run, no RST ::.

​

Git author for documentation releases

GIT_AUTHOR_NAME='Markus' \
GIT_AUTHOR_EMAIL='248457632+markus-neumannn@users.noreply.github.com' \
GIT_COMMITTER_NAME='Markus' \
GIT_COMMITTER_EMAIL='248457632+markus-neumannn@users.noreply.github.com' \
git commit -m "docs: …"

​

Standard release procedure

​

Gate A — Local

1. Working tree = source of truth; no full RST re-migration unless needed.
2. Stage: product Ext* / EXT* trees, License/, hubs, docs.json, custom.css, _static/, index.md, context.md when requested.
3. Exclude by default: RST Format */, scripts/remigration/*, scripts/live_e2e_qa/*, logs, JSON QA reports.
4. Nav/page count changes → python3 scripts/compute_doc_stats.py.
5. mintlify validate (Node 20).
6. Preview smoke on :3001 for touched URLs (restart preview if 500).
7. Review git diff --cached.

​

Gate B — GitHub

git remote -v && git branch --show-current
git push markus HEAD:master    # live
git push origin HEAD:master    # org mirror when requested

​

Gate C — Mintlify

​

Gate D — Production QA

​

Documentation conventions (Mintlify)

​

Links

• Internal: /en/latest/ExtNsT3AA/FeatureGuide/... (full product path).
• Wrong: /en/latest/FixHub/Index, /en/latest/Dashboard/Index, /en/latest/en/latest/... (double prefix).

​

Feature Guide hub (ExtNsT3AA/FeatureGuide/Index.md)

• <CardGroup> with Lucide icons (docs.json → "icons": { "library": "lucide" }).
• Working examples: layout-dashboard, image, sliders-horizontal, scan, wrench, file-text, type, accessibility.
• Broken examples: sliders, text (empty icon on live).

​

Embeds

• Supademos: <div className="t3-embed"><iframe … allow="clipboard-write; fullscreen" …></iframe></div>
• Prefer keeping Supademos when user removes static screenshots of the same screen.
• Human Expert: no Supademo on page when user requested removal.

​

RST → MD hygiene

• No .. code-block::, no standalone ::, no :ref: — use Markdown links and fenced code.
• Tables: GitHub-flavored; fix converter damage before release.

​

Images

• Prefer WebP where repo already migrated; do not leave MD pointing at deleted PNG/JPEG.
• User may remove overview images from Feature Guide pages intentionally; do not re-add without ask.

​

T3AA remigration (controlled)

​

Agent prompting cheat sheet (reply like their release engineer)

1. Small content fix — edit MD, one-line summary, note local-only unless they said deploy.
2. Release request — gates A–D, commit hash, both remotes, live poll result, honest NOT VERIFIED items.
3. “Is it live?” — curl/check live HTML; explain fork vs origin if mismatch.
4. Icons / UI — Playwright or fetch live; show what was wrong (invalid Lucide name vs deploy lag).
5. Never claim all pages tested unless crawled.
6. Commits — Markus author; message style: docs: … or chore: trigger Mintlify ….

​

Do not

• Push without user approval (except when explicit release/deploy task).
• Push only to origin and call deployment done.
• Force-push, invent emails, commit secrets or remigration noise.
• Re-add removed screenshots or patronizing TYPO3 steps without user ask.
• Hardcode homepage page/product counts (use compute_doc_stats.py).
• Use Node 25+ for Mintlify CLI.

​

Quick checklist

• Audience-appropriate prose (TYPO3-professional, not beginner)
• Local validate + preview OK
• Commit author = Markus (if committing)
• git push markus HEAD:master for live
• git push origin HEAD:master if org sync requested
• Mintlify Activity Successful
• Live URL shows intended content (specific checks, not just 200)

​

Related files