Restore site-first translation workflow and shared playbook

.agents/agents.md

@@ -11,6 +11,7 @@ Use the root PowerShell entry point for builds and validation.
 
 Preserve Hugo module internals and deliberate multilingual guide behavior. Internal refactoring is deferred until all consumers have adopted and been verified.
 Each guide site owns its bespoke wrapper and any number of guides. Never infer a fixed guide count.
+Translation workflow authority lives in OGP's distributed instructions, skills and Core human-operated procedure. Read the applicable installed version and Prepare evidence before advising a consumer; report missing capabilities transparently instead of improvising bypasses. Adding a language through guide.transcreate is site-scoped: production exclusion, configuration, i18n, localized wrapper and site-owned data, then eligible empty guide scaffolds. Body translation is a separately selected stage; per-edition Core boundaries do not narrow the site workflow. Preserve protected, populated and PDF-only/fallback content. Route status to guide.transstatus and source-change reconciliation to guide.transreconcile. Instructions guide all agents and people; they are not independent permission enforcement.
 Never enable Minionese in production. Preserve protected/source PDFs; do not regenerate supplied files.
 Hugo front matter must not contain lang; Pandoc receives language metadata separately.
 
@@ -35,3 +36,5 @@ Root AGENTS.md and CLAUDE.md are symbolic links to this canonical file. Keep the
 Do not create or use Git worktrees without the user's explicit permission. Work in the existing HugoGuides checkout; never place a repository checkout inside another repository.
 
 Use one working branch and one PR for the agreed work. Obtain Martin's explicit approval before creating branches. Switching between existing branches does not require approval. Do not edit another branch remotely to bypass this rule.
+
+Use the reusable [translation playbook](../system/OpenGuidePlatform.Agents.Integration/translation-playbook.md) for contributor journeys and review handoffs. Consumer documentation supplies site-specific policy and design only; reusable translation procedures belong in OGP.

docs/using/translation-playbook.md

@@ -0,0 +1,5 @@
+# Translation playbook
+
+The reusable [translation playbook](../../system/OpenGuidePlatform.Agents.Integration/translation-playbook.md) is distributed in the OGP package. It covers team preparation, site-first translation, local verification, PR/canary review, preview language validation and publication approval, with agent and PowerShell routes.
+
+Consumer documentation supplies only its site-specific editorial and delivery arrangements. Use the playbook from the installed package alongside its matching Core procedure.

readme.md

@@ -132,7 +132,7 @@ To test another platform without changing your installation lock:
 
 For an explicit diagnostic override, use `-PlatformRelease` locally or `platform-release` in the workflow. This does not update the installation; the selected release must still match the site's native Hugo dependency. Routine builds need neither override. Add `-PlatformRelease` to an Update command to install a specific release. The ZIP must have its `release-manifest.json` alongside it. Release overrides require an available compatible release and its coordinated Hugo dependency; use the installer to adopt a different dependency permanently. `Production` selects a non-prerelease platform package; it does not deploy the site. A release predating these module entry points cannot provide the new operations.
 
-For translations, contributors, guide editions and PDFs, use the [publishing commands](system/OpenGuidePlatform.PowerShell.Core/README.md) or the [shared agent skills](system/OpenGuidePlatform.Agents.Integration/skills/USAGE.md). PDF generation additionally needs Pandoc, XeLaTeX and the fonts required by your guide. Supplied and protected PDFs are preserved.
+For the volunteer translation journey, use the [translation playbook](system/OpenGuidePlatform.Agents.Integration/translation-playbook.md). For translations, contributors, guide editions and PDFs, use the [publishing commands](system/OpenGuidePlatform.PowerShell.Core/README.md) or the [shared agent skills](system/OpenGuidePlatform.Agents.Integration/skills/USAGE.md). PDF generation additionally needs Pandoc, XeLaTeX and the fonts required by your guide. Supplied and protected PDFs are preserved.
 
 Sites with declared JavaScript-created anchors also need Node.js 20 or newer and npm. Validate restores its browser tools into `.processing/` on first use and checks the built pages without contacting the live site. Later runs reuse that cache.
 

system/OpenGuidePlatform.Agents.Integration/instructions/guide-site.md

@@ -17,7 +17,13 @@ Shared skills are in .agents/skills. To load the installed Core module in PowerS
     $platform = ./.OpenGuidePlatform/Resolve-OpenGuidePlatform.ps1 -WorkspaceRoot $PWD -UseInstalled
     Import-Module "$platform/system/OpenGuidePlatform.PowerShell.Core/OpenGuidePlatform.PowerShell.Core.psd1"
 Run Prepare and use its generated discovered-site.json inventory for Core operations. Review any intended publishing change before applying it.
-For source-language guide body corrections, use Get-GuideContent to select the discovered guide, edition and its source language; use Set-GuideContent with the reviewed SHA-256 and candidate body. For translated documents, including typo fixes, use Set-GuideTranslation with that edition's reviewed source and target hashes. Translation availability is per edition: never infer, create or require a translation in another version merely because it exists in the selected version. Front matter and protected resources must remain intact. Follow the complete human-operated workflow in the installed Core README; the same commands and build checks apply with or without an agent.
+Route adding a language to guide.transcreate: this is site-scoped configuration, i18n, localized wrapper (including guide roots/history/translations), site-owned localized data and then empty eligible guide scaffolds. Use Get-GuideSiteTranslationWork and the installed TranslationReadiness README. Disable the language in production before other creation; preserve existing translations and protected/PDF-only/fallback intent. Translate guide bodies only in a separately selected stage. Do not confuse an individual Core command's edition boundary with the scope of adding a language to the site.
+
+Route read-only translation status to guide.transstatus and source-change comparisons to guide.transreconcile. For source-language guide body corrections, use Get-GuideContent to select the discovered guide, edition and its source language; use Set-GuideContent with the reviewed SHA-256 and candidate body. For translated documents, including typo fixes, use Set-GuideTranslation with that edition's reviewed source and target hashes. An individual body edit never requires another edition to be translated. Front matter and protected resources must remain intact. Follow the complete human-operated workflow in the installed Core README; the same commands and build checks apply with or without an agent.
+
+Read the resolved installed instructions and report the package version and Prepare evidence used. Report unsupported operations, missing tooling and incomplete evidence explicitly; do not invent inventory, silently narrow a site request or bypass a missing operation with direct writes. Use the coordinated Update workflow when an installed version lacks the required capability. Keep implemented work, empty scaffolds, editorial review, verification and production approval distinct.
 
 These instructions guide Codex, Claude and GitHub Copilot; they do not enforce permissions.
 Independent managed agent controls remain an explicit adoption blocker.
+
+For team preparation, PR/canary review and preview language validation, read system/OpenGuidePlatform.Agents.Integration/translation-playbook.md in the resolved installed package. Keep consumer-specific editorial and delivery arrangements in the consumer repository; report reusable platform gaps upstream.

system/OpenGuidePlatform.Agents.Integration/skills/USAGE.md

@@ -4,6 +4,16 @@ Installation and Update distribute these skills and the matching Core module. Fo
 
 In an adopted site, resolve `$platform` through `./.OpenGuidePlatform/Resolve-OpenGuidePlatform.ps1 -WorkspaceRoot $PWD -UseInstalled`, then import Core from that package. Run Prepare with a fresh output directory and `-PlatformSource Path -PlatformPath $platform` to use that same version. Load `<output>/discovered-site.json` with Import-GuidePolicy. Keep WorkspaceRoot set to the consumer repository root. Explicit policy inputs remain supported for callers that use them; ordinary contributors use discovery.
 
+```powershell
+$workspace = $PWD.Path
+$platform = ./.OpenGuidePlatform/Resolve-OpenGuidePlatform.ps1 -WorkspaceRoot $workspace -UseInstalled
+Import-Module "$platform/system/OpenGuidePlatform.PowerShell.Core/OpenGuidePlatform.PowerShell.Core.psd1" -Force
+Get-Content "$platform/platform.json"
+Get-Command Get-GuideSiteTranslationWork, Get-GuideTranslationWork, Set-GuideWrapperTranslation, Set-GuideTranslation
+```
+
+Read the instructions and Core README from that resolved package, and identify its version in the report. If the installed version lacks a required command, report the exact unsupported operation and use the coordinated Update procedure when authorized. Do not import a different version or improvise a direct-write substitute to get past a missing operation.
+
 The discovered inventory describes an unrestricted collection of guides; counts in fixtures are examples. Core decisions have no agent dependency. Agent instructions do not grant write authority. Independent enforcement requires an externally configured AgentControls evaluator or managed client; installation alone does not enable it. Mutation commands support WhatIf and refuse protected resources under the supplied policy.
 
 Use the shared Prepare report for readiness. Core supports reviewed wrapper Markdown, YAML catalogue and language-configuration edits; preserve the consumer's multilingual structure and bespoke wrapper. Prepare validates declared generated-PDF receipts; generation and receipt recording are explicit operations.
@@ -23,10 +33,30 @@ Get-GuideInventory and Get-GuideWrapperStatus are useful detailed diagnostics. G
 
 ## Reviewed wrapper translation edits
 
+`guide.transcreate` adds a language to the site, not just one guide edition. After Prepare, load `$policy = Import-GuidePolicy -Path "$readinessOutput/discovered-site.json"` and run `Get-GuideSiteTranslationWork -WorkspaceRoot $workspace -Policy $policy -Language 'your-language'`. Review configuration, catalogue, wrapper Markdown (including guide roots, history and translations pages), site-owned localized data and eligible guide scaffolds. This diagnostic does not mutate files or certify readiness. Follow the site-first procedure in the installed TranslationReadiness README: production exclusion first, localized site experience next, empty eligible guide bodies last. Body translation is a separately selected stage. Preserve declared PDF-only/fallback intent and populated targets; do not manufacture a fixed file list from a different site.
+
+
 For guide translation creation and reconciliation, read `system/OpenGuidePlatform.PowerShell.Core/TranslationReadiness/README.md` in the resolved package. Get-GuideTranslationWork reports source/target content and optional explicit Git comparisons; New-GuideTranslation starts scaffolding; Test-GuideTranslation checks candidates; Set-GuideTranslation applies against reviewed source/target hashes. Both humans and skills use these commands. Refresh Prepare after scaffolding rather than editing discovered inventory. Source comparisons are review evidence, not inferred translator provenance.
 
-Use Set-GuideWrapperTranslation for exact candidate text in a language-specific wrapper Markdown file, its i18n YAML catalogue, or a selected language entry in hugo.yaml/hugo.production.yaml. Supply WorkspaceRoot, Policy, Language, RelativePath and CandidateContent. Existing files require their reviewed ExpectedSha256; scaffolding never silently replaces a populated file. The command checks supplied protected-path policy and refuses guide content.
+Use Set-GuideWrapperTranslation for exact candidate text in a language-specific wrapper Markdown file, its i18n YAML catalogue, or a selected language entry in hugo.yaml/hugo.production.yaml. Supply WorkspaceRoot, Policy, Language, RelativePath and CandidateContent. Existing files require their reviewed ExpectedSha256; scaffolding never silently replaces a populated file. The command checks supplied protected-path policy and refuses guide edition bodies and resources.
+
+For discovered localized JSON data, the same command requires `ExpectedSourceSha256` and explicit `JsonTextPaths` selecting reviewed RFC 6901 string leaves. Preserve machine values and all unselected content. Other unsupported site-owned resources must be reported explicitly, not silently omitted or edited through a bypass.
 
 For a new language, first apply a reviewed production configuration candidate with that language disabled, then its main language configuration and wrapper/catalogue files. Configuration edits preserve all unrelated settings and other languages. Preserve the site's existing wrapper paths, metadata, rendering conventions and existing legacy aliases; do not create new shared download aliases. Translate the candidate text within the requested scope rather than inventing a universal wrapper layout.
 
 Each file operation supports WhatIf and publishes through a staged write. Several files are not one transaction: inspect partial progress if an operation fails and rerun Prepare before claiming readiness. Resolved hashes prevent observed stale edits; cooperative locks are not independent enforcement. Run Build/Validate after the complete reviewed change.
+
+## Short requests for people using an agent
+
+- "Use guide.transstatus to show what remains for Kannada across this site. Report the installed version, Prepare evidence, wrapper work and guide bodies separately. Do not edit."
+- "Use guide.transcreate to add Kannada to this site, disabled in production. Localize the site wrapper and create eligible empty guide scaffolds. Keep guide body translation for later; show blocked operations and review outputs."
+- "Use guide.transcreate to translate the body of the guide and edition I select into Kannada, using the reviewed source and target hashes. Show the outline, candidate findings and build results."
+- "Use guide.transreconcile to compare this selected translation with the source revision I provide. Report the differences before applying changes."
+
+These requests route work to the same installed commands used by a person in PowerShell. They do not grant publication approval or provide independent permission enforcement.
+
+For the team journey, review handoffs and context-rich skill requests, follow `system/OpenGuidePlatform.Agents.Integration/translation-playbook.md` in the resolved installed package. This usage file is also copied into consumer `.agents/skills`; the playbook remains in the package:
+
+```powershell
+Get-Content "$platform/system/OpenGuidePlatform.Agents.Integration/translation-playbook.md"
+```

system/OpenGuidePlatform.Agents.Integration/skills/guide.contributions/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: guide.contributions
-description: "Create guide or translation-team contributor YAML, apply a reviewed update to one existing contributor, or resolve an edition's credits."
+description: "Create guide or translation-team contributor YAML, append one reviewed translation-team member, apply a reviewed update to one existing contributor, or resolve an edition's credits."
 ---
 
 Read [Core usage](../USAGE.md), load the consumer policy, and select the declared guide. Contributor data is the only source of guide credits: `data/contributions/<guide>.yml` holds the guide's own people (roles `creator`, `contributor`, `reviewer`, `involved`; creators are the authors) and `data/contributions/<guide>.<lang>.yml` holds one translation team (roles `translator`, `reviewer`). Every record needs `name`, `role` and `contributions` (the edition identifiers it applies to); `weight` orders records and `localizedNames` maps a language code to the name shown in that language. Do not put `author` or `translators` in guide front matter; Prepare blocks them.
@@ -11,4 +11,6 @@ Preserve supplied URLs, edition references and other contributor metadata; do no
 
 For an authorized update, read the original bytes and SHA-256 and prepare CandidateYaml with the minimal requested diff. Preserve comments, formatting, contributor order and every unselected record. Apply with `Update-GuideContributions -WorkspaceRoot $WorkspaceRoot -Policy $policy -GuideId $GuideId -ContributorName $Name -ExpectedSha256 $OriginalHash -CandidateYaml $CandidateYaml [-Language $Language]`. The command validates semantic scope and writes the candidate text exactly; it does not reconstruct formatting for you. Review the diff for comment/format preservation.
 
+To add one translator or reviewer to an existing translation-team file, use `Add-GuideContribution -WorkspaceRoot $WorkspaceRoot -Policy $policy -GuideId $GuideId -Language $Language -ExpectedSha256 $OriginalHash -CandidateYaml $CandidateYaml`. Read the full file as UTF-8 without dropping its BOM, retain every existing byte as the candidate prefix, and append exactly one record. Supply only the person's agreed details, a valid translation role and existing edition references. The command refuses duplicate identities (GitHub username when present, otherwise name), changes to existing records or comments, and protected paths. It supports WhatIf and checks the hash again before staged replacement. Adding to the guide's own contributor file is outside this operation.
+
 The update must select exactly one existing name; it cannot rename, add, remove or reorder contributors. A stale hash means re-read and review the changed file, never refresh the hash blindly to bypass the refusal. The cooperative lock cannot prevent edits by programs that ignore it. Use WhatIf to inspect the operation and run the consumer build after an authorized change; Prepare reports invalid roles, unknown editions, duplicates and missing creators or translators. `Get-GuideCredits` shows the authors, contributors and translators a PDF cover will use. Report the changed path and verification result.