Make shared contributor guidance usable without bespoke translation manuals

docs/architecture/contributor-guide-coverage.md

@@ -0,0 +1,25 @@
+# Replacing procedural translation companions
+
+Acceptance baseline: reusable translation explanations must be available in the version-matched OGP contributor guide, without requiring a language-specific procedural PDF. Sites retain local policy and delivery arrangements; teams retain language decisions. No consumer documentation or protected PDF is changed by this platform work.
+
+The Kannada companion supplied the following useful categories. Its commands and historical capability claims are reference material, not current authority. The owning shared component is `OpenGuidePlatform.Agents.Integration`; exact operations remain owned by Core and the installed skills.
+
+| Companion material | Shared destination | Material that remains site/language-owned |
+|---|---|---|
+| Plain-English terminology, roles and pictures | [System](../../system/OpenGuidePlatform.Agents.Integration/contributor-guide/system.md), [files](../../system/OpenGuidePlatform.Agents.Integration/contributor-guide/files.md), glossary and four SVGs | Named people and local contacts |
+| Ordered tasks and handoffs | [First translation](../../system/OpenGuidePlatform.Agents.Integration/contributor-guide/first-translation.md) | Selected guides/editions and actual approvals |
+| Mac terminal versus assistant input, prerequisites and clone | [Setup](../../system/OpenGuidePlatform.Agents.Integration/contributor-guide/setup.md) | Site requirements exceeding platform minimums |
+| Production exclusion, website words, scaffolds and body boundaries | [Add language](../../system/OpenGuidePlatform.Agents.Integration/contributor-guide/add-language.md), [guide translation](../../system/OpenGuidePlatform.Agents.Integration/contributor-guide/translate-guide.md), matching Core procedures | Bespoke wrapper design and unsupported operations needing maintainer work |
+| Human review tables and applying feedback | [Review wording](../../system/OpenGuidePlatform.Agents.Integration/contributor-guide/review-wording.md) | Agreed glossary, source/candidate evidence, actual feedback |
+| File-by-file lists | Discovery and supported-operation reports explained in [status](../../system/OpenGuidePlatform.Agents.Integration/contributor-guide/status.md) | Actual site inventory; no universal guide count or file list |
+| Save work, open an early draft PR and find review environments | [Validation/submission](../../system/OpenGuidePlatform.Agents.Integration/contributor-guide/validation.md) | Git permissions, destination branches, canary configuration and contributor agreements |
+| Credits, script rendering and PDFs | [Credits/PDFs](../../system/OpenGuidePlatform.Agents.Integration/contributor-guide/credits-pdfs.md), review-wording | Consented identities, script conventions, approved fonts and design decisions |
+| Promotion, useful notes and later source changes | First-translation, [journey](../../system/OpenGuidePlatform.Agents.Integration/contributor-guide/translation.md), [reconciliation](../../system/OpenGuidePlatform.Agents.Integration/contributor-guide/update-translation.md) | Guardian approval and actual release policy/actions |
+
+## Validation and limits
+
+Require every linked shared page and asset to ship in GuideSite and retain valid local navigation. Run root platform acceptance, including package validation and sample workflows. Independently walk both assistant and manual routes against Core contracts and inspect the novice review handoff. The review sheet is a human aid, not an import schema, permission mechanism or replacement for candidate checks.
+
+For purpose validation, a real newcomer should follow the first-translation path using only shared OGP guidance plus local policy/decision notes. Record where they need an explanation from the old companion or another person; move reusable missing explanations into OGP. Technical checks and an agent role-play do not establish beginner usability. Completion of such a real-user study must be recorded before claiming this purpose verified.
+
+Publication/adoption is separate from implementation: these sources must be released and the consumer must adopt the matching package or link to that revision before its contributors receive them. A clean local build does not make the old companion obsolete for an unchanged consumer installation. Do not delete its language decisions or promise that site-specific work has been completed by this platform change.

docs/using/translation-playbook.md

@@ -3,3 +3,5 @@
 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.
+
+New to the system? Start with the [contributor guide](../../system/OpenGuidePlatform.Agents.Integration/contributor-guide/README.md) for setup, task explanations and diagrams.

examples/reference-guide-site/content/Guide2/_index.md

@@ -1,7 +1,7 @@
 ---
 title: "Guide 2 - Extended Edition"
 short_title: "Guide 2"
-slug: "guide-2"
+slug: "guide2"
 Type: "guide"
 Layout: "root"
 description: "Guide 2 is a comprehensive resource for understanding and implementing advanced practices in knowledge work contexts. It covers extended practices and real-world applications to enhance workflow efficiency and team collaboration."

examples/reference-guide-site/content/Guide2/_index.min.md

@@ -1,7 +1,7 @@
 ---
 title: "Guide 2 Banana Booky - Big Big Edition"
 short_title: "Guide 2 Banana Booky"
-slug: "guide-2"
+slug: "guide2"
 Type: "guide"
 Layout: "root"
 description: >

readme.md

@@ -4,6 +4,8 @@
 
 OpenGuidePlatform provides the shared publishing system beneath your site. Publish one document, a collection, or a growing library. Keep past editions available, manage translations independently, and offer web and PDF access to your publications.
 
+For plain-English tasks and diagrams, start with the [Contributor guide](system/OpenGuidePlatform.Agents.Integration/contributor-guide/README.md). It ships with GuideSite; use its version-matched instructions alongside site policy.
+
 Your site owns its front end: branding, navigation, page layouts and the surrounding experience. Use the shared Hugo modules within a bespoke site, or make your guides one part of a larger website. The platform does not prescribe a single site design.
 
 It provides:

system/OpenGuidePlatform.Agents.Integration/README.md

@@ -6,7 +6,16 @@ Current contents:
 
 - `skills/`: the seven publishing skills, usage instructions, license and provenance. Installation places these in the consumer's `.agents/skills/` directory.
 - `instructions/guide-site.md`: canonical distributed contributor instructions. Installation uses these for `.agents/agents.md`, the root instruction symlinks and Copilot instructions.
+- [Contributor guide](contributor-guide/README.md): shared human-facing task pages and accessible SVG diagrams, included in the GuideSite package.
 
 Future agent definitions, Claude workflows/commands, client hook adapters and configuration templates belong here in clearly named directories. They are not implemented or enabled by this rename.
 
 Executable validation belongs in `OpenGuidePlatform.PowerShell.AgentControls`. Hooks must be thin calls to those PowerShell operations. Skills and workflows call the appropriate publishing/build module rather than duplicate its implementation. Consumer configuration remains reviewed through installation/update; adding this component does not change agent permissions.
+
+## Maintaining contributor documentation
+
+Keep the beginner explanations and expert command references on the same supported workflow. Reusable explanations belong here; consumer sites retain local policy and link to the installed release's source revision. No consumer update or deployment is implied by changing these sources.
+
+Run the platform root `./build.ps1 -Version 0.0.0-local`. Core tests check page presence, local links/heading anchors and accessible SVG structure, including rejection of missing references. Package validation runs the same checker against extracted release bytes; normal packaging includes this component recursively. Packaged sample acceptance exercises preview/production builds and disposable human-operated content and site-language workflows.
+
+Render and visually inspect all four SVGs after diagram edits, including a narrow viewport. Check command examples against the matching Core contracts and independently review the manual and assistant journeys. Technical checks do not establish beginner usability: ask a new contributor to complete setup, first assessment, a selected change and review using only the docs, recording help required and revising confusing steps. Retain source revision, installed version, artifacts and results with review evidence. Do not claim that walkthrough happened unless it did.

system/OpenGuidePlatform.Agents.Integration/contributor-guide/README.md

@@ -0,0 +1,51 @@
+# Start here
+
+You can help a guide site without being a programmer. You need knowledge of the subject or language; one technical volunteer can operate the tools while other people translate and review. An AI assistant is optional.
+
+These pages explain the work. The linked Core procedures supply the exact commands for this OGP release. Use your site's contribution rules alongside them: the site decides editorial policy, contacts and publication approval.
+
+**First translation? Follow [Your first translation, from agreement to review](first-translation.md).** It tells each person what to do, what to hand over and when the team can move on. You do not need to assemble a separate procedure or know Git to review wording.
+
+## Choose your activity
+
+| I want to… | Start with |
+|---|---|
+| Understand where things belong | [How the system fits together](system.md) |
+| Prepare my computer | [Setup](setup.md) |
+| Understand unfamiliar files and terms | [Files and changes](files.md) |
+| Organise a translation team | [Translation journey](translation.md) |
+| Complete my first translation with the team | [First translation walkthrough](first-translation.md) |
+| Translate or review wording without running commands | [Review wording](review-wording.md) |
+| Find what is missing | [Check translation status](status.md) |
+| Introduce a language | [Add a site language](add-language.md) |
+| Translate one guide edition | [Translate a guide](translate-guide.md) |
+| Update an existing translation | [Update a translation](update-translation.md) |
+| Correct or add content | [Content changes](content.md) |
+| Credit people or prepare downloads | [Credits and PDFs](credits-pdfs.md) |
+| Check and submit work | [Validation and publication](validation.md) |
+| Recover from a problem | [Troubleshooting and glossary](troubleshooting.md) |
+
+Each task explains the purpose, human decisions, supported route and evidence needed. Experienced contributors can go directly to [Core commands](../../OpenGuidePlatform.PowerShell.Core/README.md), the [translation procedure](../../OpenGuidePlatform.PowerShell.Core/TranslationReadiness/README.md) or [assistant skill usage](../skills/USAGE.md).
+
+## Read the version your site uses
+
+From the guide-site repository root, in PowerShell:
+
+```powershell
+$platform = ./.OpenGuidePlatform/Resolve-OpenGuidePlatform.ps1 -WorkspaceRoot $PWD -UseInstalled
+Get-Content "$platform/platform.json"
+Join-Path $platform 'system/OpenGuidePlatform.Agents.Integration/contributor-guide/README.md'
+```
+
+Open the printed Markdown path in an editor with Markdown preview. The diagrams are included beside the pages. This resolves the installed package; uncached restoration may require network access and authenticated release access. If restoration fails, see [troubleshooting](troubleshooting.md).
+
+For browser reading, find the same path in the OGP GitHub repository at the immutable `sourceCommit` printed in `platform.json`. Do not assume the repository's main branch describes your installed release. A guide site can link to that revision and retain its own short policy page; it need not copy these procedures. A dedicated documentation hosting service is not required to read them on GitHub.
+
+The technical volunteer can print the exact browser link for the team:
+
+```powershell
+$packageInfo = Get-Content "$platform/platform.json" -Raw | ConvertFrom-Json
+"https://github.com/nkdAgility/OpenGuidePlatform/blob/$($packageInfo.sourceCommit)/system/OpenGuidePlatform.Agents.Integration/contributor-guide/README.md"
+```
+
+That link works when the package source commit is available in the repository. For an unpublished local build, share the packaged Markdown instead. Site entry pages need only this version-matched link, local policy/contact links and the actual review-environment arrangements. Language notes retain glossary and editorial decisions; they do not need another copy of the workflow.

system/OpenGuidePlatform.Agents.Integration/contributor-guide/add-language.md

@@ -0,0 +1,19 @@
+# Add a site language
+
+The goal is to make the surrounding website usable in the language before translating selected guide bodies. Start with [agreed scope](translation.md) and a fresh [status report](status.md). A technical volunteer applies reviewed text; translators need not edit JSON or YAML themselves.
+
+Follow the [Core site-first procedure](../../OpenGuidePlatform.PowerShell.Core/TranslationReadiness/README.md#add-a-language-across-the-site) for exact commands and candidates. Its order matters:
+
+1. Add the language **disabled in production first**, then add its main language configuration. Preserve unrelated settings and every other language.
+2. Translate discovered interface messages and wrapper pages: homepage, guide landing pages, history and translation listings.
+3. Translate selected reader-facing strings in discovered site-owned data. Preserve keys, URLs, placeholders and machine values. JSON pointers select specific string values; they are not a request to translate every string.
+4. Refresh Prepare and create only eligible, agreed empty guide scaffolds. Do not replace existing translations or convert protected, PDF-only or fallback states.
+5. Refresh discovery, run preview and production builds and inspect the result through [validation](validation.md).
+
+Use the [review-sheet template and feedback handoff](review-wording.md) for source path, field/section, source text, proposed translation and feedback, tied to source/candidate evidence. Translators can complete it without editing YAML/JSON. The technical volunteer applies agreed rows using the original reviewed hashes, lists conflicts for the guardian, and returns the rendered result for review. An old sheet must be reconciled if the source or target changed; the sheet never replaces supported checks.
+
+With an assistant: “Use guide.transcreate to add LANGUAGE, disabled in production, following the installed site-first procedure and our glossary. Localize the website and create agreed eligible empty scaffolds. Leave guide bodies untranslated. Present review text, preserved states and blockers separately.”
+
+**Success:** the website-language work and empty scaffolds are accurately reported; rendered preview and production exclusion have been checked. Any failed checks remain visible. Do not describe scaffolds as completed translations. **Next:** [selected guide bodies](translate-guide.md).
+
+**If interrupted:** several files are separate operations. Inspect the actual diff, refresh Prepare and reconcile completed work before resuming. Missing configuration or unsupported custom metadata/schema operations must be reported; do not copy another language's file list or bypass the installed writer.

system/OpenGuidePlatform.Agents.Integration/contributor-guide/content.md

@@ -0,0 +1,19 @@
+# Correct or add content
+
+First agree the change through the site's contribution process. Identify whether you are editing an existing source-language guide body, a translation, website text, or introducing a new page/edition. They have different owners and supported operations.
+
+| Change | Supported route |
+|---|---|
+| Correct or add paragraphs in an existing source guide | [Core correct-an-existing-guide workflow](../../OpenGuidePlatform.PowerShell.Core/README.md#correct-an-existing-guide) |
+| Correct translated text | [Update a translation](update-translation.md) with same-edition source/target checks |
+| Localize surrounding website text | [Site-language workflow](add-language.md) for supported wrapper resources |
+| Introduce a new guide/page, restructure metadata or change routing | Agree the site-owned design and supported operation with maintainers first |
+| Create a draft edition snapshot | Review the [Core edition commands](../../OpenGuidePlatform.PowerShell.Core/README.md) and the installed [historical-version skill](../skills/guide.historicalversion/SKILL.md); a snapshot is not publication |
+
+For an existing source body, run discovery, use `Get-GuideContent` to select its actual guide, edition and source language, and save a separate candidate body. Edit that candidate in your editor, preview `Set-GuideContent` with `-WhatIf`, then apply with the original reviewed hash. Inspect `git diff` and [validate](validation.md). The linked Core workflow gives the complete runnable example.
+
+Do not guess a path from another site's guide count or copy an edition directory manually as a substitute for a supported workflow. Source correction preserves front matter and protected resources. If your request includes unsupported metadata or new resource types, report that boundary; an existing-body writer cannot create arbitrary pages.
+
+With an assistant: “Read the site's instructions and use installed Core discovery to select the source body for GUIDE, EDITION. Prepare the agreed correction as a candidate, preserve metadata and resources, show the diff and run the required builds.”
+
+**Success:** the diff contains the agreed addition/correction in the intended component, other content remains intact, and local verification is recorded. Follow site editorial review before publication. A PDF may need explicit regeneration if its generated receipt becomes stale; supplied PDFs remain protected.