diff --git a/docs/architecture/contributor-guide-coverage.md b/docs/architecture/contributor-guide-coverage.md new file mode 100644 index 0000000..04837c7 --- /dev/null +++ b/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. diff --git a/docs/using/translation-playbook.md b/docs/using/translation-playbook.md index bc5fd2d..bc6eee5 100644 --- a/docs/using/translation-playbook.md +++ b/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. diff --git a/examples/reference-guide-site/content/Guide2/_index.md b/examples/reference-guide-site/content/Guide2/_index.md index b6e2c17..2ba5917 100644 --- a/examples/reference-guide-site/content/Guide2/_index.md +++ b/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." diff --git a/examples/reference-guide-site/content/Guide2/_index.min.md b/examples/reference-guide-site/content/Guide2/_index.min.md index 39c6554..3331719 100644 --- a/examples/reference-guide-site/content/Guide2/_index.min.md +++ b/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: > diff --git a/readme.md b/readme.md index 4ebd718..97aa321 100644 --- a/readme.md +++ b/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: diff --git a/system/OpenGuidePlatform.Agents.Integration/README.md b/system/OpenGuidePlatform.Agents.Integration/README.md index e44d32a..1fd6b34 100644 --- a/system/OpenGuidePlatform.Agents.Integration/README.md +++ b/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. diff --git a/system/OpenGuidePlatform.Agents.Integration/contributor-guide/README.md b/system/OpenGuidePlatform.Agents.Integration/contributor-guide/README.md new file mode 100644 index 0000000..10333e7 --- /dev/null +++ b/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. diff --git a/system/OpenGuidePlatform.Agents.Integration/contributor-guide/add-language.md b/system/OpenGuidePlatform.Agents.Integration/contributor-guide/add-language.md new file mode 100644 index 0000000..0950124 --- /dev/null +++ b/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. diff --git a/system/OpenGuidePlatform.Agents.Integration/contributor-guide/content.md b/system/OpenGuidePlatform.Agents.Integration/contributor-guide/content.md new file mode 100644 index 0000000..ac10539 --- /dev/null +++ b/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. diff --git a/system/OpenGuidePlatform.Agents.Integration/contributor-guide/credits-pdfs.md b/system/OpenGuidePlatform.Agents.Integration/contributor-guide/credits-pdfs.md new file mode 100644 index 0000000..fd583cb --- /dev/null +++ b/system/OpenGuidePlatform.Agents.Integration/contributor-guide/credits-pdfs.md @@ -0,0 +1,21 @@ +# Credits and PDFs + +Credits recognise people; PDFs are published artifacts that need their own checks. Neither should be an accidental side effect of a text edit. + +## Credit people with consent + +Ask people which name and optional profile link they consent to publish. Guide creator/contributor records and translation-team records are separate. Use [contributor commands](../../OpenGuidePlatform.PowerShell.Core/README.md#guide-credits) or the installed [contributions skill](../skills/guide.contributions/SKILL.md) for the supported operation. Adding a person and updating an existing record have different contracts. + +Structured credits do not replace any acknowledgement section required by the site's editorial policy. Preserve existing people and roles; report unsupported removals, renames or reordering instead of using an unrelated operation. Review the displayed website and PDF credits, not only YAML syntax. + +## Prepare eligible downloads + +Ask the maintainer whether the selected download is generated or supplied/protected. Only explicitly eligible generated PDFs may be generated. Preserve supplied originals and their filenames/bytes. + +Follow the [PDF skill](../skills/guide.genpdfs/SKILL.md) and [Core PDF reference](../../OpenGuidePlatform.PowerShell.Core/README.md#pdf-configuration): inspect the plan, diagnose fonts and tools, agree configuration, generate the selected artifact, visually inspect actual pages and record the required receipt. A receipt records generation evidence; it does not approve appearance. Ordinary site builds do not generate PDFs automatically. + +Inspect representative text and titles: glyphs, conjunct shaping, reading direction, italics/adaptation marks, page breaks, links, cover fit and attribution. A font name is not proof of correct rendering. Keep font choices in PDF configuration, not guide front matter. For scripts such as Kannada, the guardian must decide how source conventions transfer before the maintainer chooses and checks presentation. + +With an assistant: “Use guide.contributions for our consented records, then guide.genpdfs to assess the selected download. Show eligibility, tools/fonts, candidate changes and required visual review. Preserve supplied PDFs.” + +**Success:** correct consented attribution is visible, eligible downloads have generation evidence and human visual review, and [Prepare/build checks](validation.md) agree. **If tools or approved fonts are missing:** report them before generation; do not silently substitute fonts or regenerate protected files. diff --git a/system/OpenGuidePlatform.Agents.Integration/contributor-guide/diagrams/candidate.svg b/system/OpenGuidePlatform.Agents.Integration/contributor-guide/diagrams/candidate.svg new file mode 100644 index 0000000..aacce15 --- /dev/null +++ b/system/OpenGuidePlatform.Agents.Integration/contributor-guide/diagrams/candidate.svg @@ -0,0 +1,26 @@ + +Review before replacing a file +Read source and target: Keep the reviewed fingerprints. Then Prepare a candidate: Propose changes in a separate file. Then Review and check: People assess meaning; tools check constraints. Then Preview and apply: Use WhatIf and original reviewed hashes. Then Inspect and build: A changed hash means reread and reconcile. + + +Review before replacing a file + +1. Read source and target +Keep the reviewed fingerprints + + +2. Prepare a candidate +Propose changes in a separate file + + +3. Review and check +People assess meaning; tools check constraints + + +4. Preview and apply +Use WhatIf and original reviewed hashes + + +5. Inspect and build +A changed hash means reread and reconcile + diff --git a/system/OpenGuidePlatform.Agents.Integration/contributor-guide/diagrams/ownership.svg b/system/OpenGuidePlatform.Agents.Integration/contributor-guide/diagrams/ownership.svg new file mode 100644 index 0000000..0f55274 --- /dev/null +++ b/system/OpenGuidePlatform.Agents.Integration/contributor-guide/diagrams/ownership.svg @@ -0,0 +1,22 @@ + +Who owns what +OGP package: Shared tools and matching instructions. Then Your local site clone: Site content and proposed changes. Then Pull request: People review the exact change. Then Site repository: Maintainers control publication. + + +Who owns what + +1. OGP package +Shared tools and matching instructions + + +2. Your local site clone +Site content and proposed changes + + +3. Pull request +People review the exact change + + +4. Site repository +Maintainers control publication + diff --git a/system/OpenGuidePlatform.Agents.Integration/contributor-guide/diagrams/publication.svg b/system/OpenGuidePlatform.Agents.Integration/contributor-guide/diagrams/publication.svg new file mode 100644 index 0000000..d462c5b --- /dev/null +++ b/system/OpenGuidePlatform.Agents.Integration/contributor-guide/diagrams/publication.svg @@ -0,0 +1,26 @@ + +From local checks to readers +Local builds and inspection: Preview and production; no deployment. Then PR canary: Maintainer-arranged technical/design review. Then Merge to preview: Language validation; corrections through PRs. Then Separate promotion approval: Guardian and maintainer decisions. Then Production release: Verify the configured public site. + + +From local checks to readers + +1. Local builds and inspection +Preview and production; no deployment + + +2. PR canary +Maintainer-arranged technical/design review + + +3. Merge to preview +Language validation; corrections through PRs + + +4. Separate promotion approval +Guardian and maintainer decisions + + +5. Production release +Verify the configured public site + diff --git a/system/OpenGuidePlatform.Agents.Integration/contributor-guide/diagrams/translation.svg b/system/OpenGuidePlatform.Agents.Integration/contributor-guide/diagrams/translation.svg new file mode 100644 index 0000000..46d50cf --- /dev/null +++ b/system/OpenGuidePlatform.Agents.Integration/contributor-guide/diagrams/translation.svg @@ -0,0 +1,30 @@ + +The translation journey +Agree people and scope: Guardian, glossary and selected editions. Then Assess the actual site: Installed version and Prepare evidence. Then Add the site language: Production disabled; localize the wrapper. Then Translate selected bodies: One explicit guide edition at a time. Then Review and validate: Language, rendering, credits and eligible PDFs. Then Decide publication separately: Guardian approval and maintainer promotion. + + +The translation journey + +1. Agree people and scope +Guardian, glossary and selected editions + + +2. Assess the actual site +Installed version and Prepare evidence + + +3. Add the site language +Production disabled; localize the wrapper + + +4. Translate selected bodies +One explicit guide edition at a time + + +5. Review and validate +Language, rendering, credits and eligible PDFs + + +6. Decide publication separately +Guardian approval and maintainer promotion + diff --git a/system/OpenGuidePlatform.Agents.Integration/contributor-guide/files.md b/system/OpenGuidePlatform.Agents.Integration/contributor-guide/files.md new file mode 100644 index 0000000..bed6a29 --- /dev/null +++ b/system/OpenGuidePlatform.Agents.Integration/contributor-guide/files.md @@ -0,0 +1,21 @@ +# Understand files and changes + +A guide page is usually Markdown: plain text with marks for headings, emphasis and links. A front matter block at its beginning stores settings. YAML and JSON hold settings and interface messages. You translate agreed reader-facing values while preserving identifiers, addresses and placeholders that the software uses. + +For example, in `Download {{ .Site.Title }}`, translate “Download” but keep `{{ .Site.Title }}` intact. In `[Read the guide](guide-url)`, translate the label and preserve the destination. A custom field is not automatically editable just because it contains English. + +## Why use a candidate? + +A candidate is a separate proposed version. Review it before asking the platform to replace the existing file. A hash (SHA-256 fingerprint) identifies the exact source or target bytes you reviewed. If another person changes a file, the old fingerprint no longer matches; reconcile the change rather than substituting a new hash blindly. + +![Read source and target, prepare a candidate, review and check, then apply only while the reviewed fingerprints still match.](diagrams/candidate.svg) + +In words: read the actual source and destination; prepare a candidate; have people review it and run the supported check; preview the operation with `-WhatIf`; apply against the original reviewed hashes; inspect the diff and build. A stale hash returns you to reading and reconciliation. A check does not approve the translation's meaning. + +## What gets shared? + +`git diff` shows edits you have not yet selected for a commit. `git diff --cached` shows the selected (staged) edits. `git status --short` also lists new, untracked files, which neither diff includes until you stage them. A commit saves a selected set of changes locally. A push sends commits to GitHub. A pull request asks the site team to review and merge them. These are separate actions, and none alone approves production publication. + +Keep `.processing`, private coordination, raw assistant logs and unconsented personal information out of commits. Preserve protected PDFs, routing metadata, explicit anchors and intentional formatting. Do not add `lang`, fonts or attribution fields to guide front matter; follow [credits and PDFs](credits-pdfs.md). + +**Next:** [translation journey](translation.md) or [content changes](content.md). **Recovery:** [stale files and other failures](troubleshooting.md). diff --git a/system/OpenGuidePlatform.Agents.Integration/contributor-guide/first-translation.md b/system/OpenGuidePlatform.Agents.Integration/contributor-guide/first-translation.md new file mode 100644 index 0000000..2561f07 --- /dev/null +++ b/system/OpenGuidePlatform.Agents.Integration/contributor-guide/first-translation.md @@ -0,0 +1,85 @@ +# Your first translation, from agreement to review + +Use this page as the team's working checklist. The linked pages belong to the same OGP package, so everyone can use one procedure. The website may contain several guides and editions; the team chooses which bodies to translate after introducing the site language. + +The **guardian** settles editorial questions, **translators** propose words, **reviewers** check them, a **technical volunteer** runs the commands, and a **maintainer** arranges review environments and publication. One person can hold several roles. Translators and reviewers can work without Git, PowerShell or an AI account: start with [reviewing wording](review-wording.md). The technical volunteer follows the command route on their behalf. + +The [translation diagram](translation.md) shows the whole journey. A technical check and an editorial decision answer different questions; neither replaces the other. + +## 1. Agree the people and the language + +**Guardian and team:** use the site's contribution channel to agree the target language/variant, the people involved and the guide editions planned for later translation. Read the site's translation policy. Decide glossary terms, treatment of licences/references, acknowledgements and any meaningful source formatting. If capitals or italics do not transfer to the target script, record the question and the guardian's decision before drafting substantial passages. + +**Hand over:** agreed scope, policy link, glossary and unresolved questions. Notes may live in the site's optional language folder described in [the journey](translation.md). Mark proposed and agreed decisions separately. Do not publish private contact details. + +**Move on when:** the team knows who decides wording and who operates the tools. The required number and type of reviewers comes from site policy, not a universal OGP number. + +## 2. Set up and find out what already exists + +**Technical volunteer:** follow [setup](setup.md), then [check status](status.md). Run the assessment rather than copying another language's files. Record the installed package version and Prepare report path. Report site-language work separately from guide-body work, and preserve existing translations, supplied PDFs and intentional fallback/PDF-only states. + +With an assistant, paste into its conversation, replacing LANGUAGE with your agreed language and code: + +> Read this site's contributor instructions and use guide.transstatus for LANGUAGE. Report the installed version, Prepare evidence, website-language work and guide bodies separately. Do not edit. Explain prerequisites and missing capabilities in plain English. + +Without an assistant, use the complete PowerShell blocks on the status page. `guide.transstatus` is a skill name, not a terminal command. + +**Move on when:** discovery is valid and the next operations are supported. If the installed package lacks a capability, hand the version and missing operation to the maintainer for a coordinated update. A failed Prepare report remains failed even when valid discovery allows a specific repair. + +## 3. Prepare the website words + +**Technical volunteer:** follow [add a site language](add-language.md) and its linked Core command examples. Disable the language in production first; then prepare language configuration, interface labels, wrapper pages and selected site-owned data. Only then create the eligible empty guide scaffolds agreed in scope. Leave body translation for step 5. + +With an assistant: + +> Use guide.transcreate to add LANGUAGE to this site, disabled in production, using the installed site-first procedure and our glossary. Prepare website wording and agreed eligible empty scaffolds. Leave guide bodies untranslated. Present a review table tied to the exact source and candidate, and list preserved states, incomplete checks and unsupported operations. Follow the site's permissions for applying changes and Git actions. + +**Translators and reviewers:** use [review wording](review-wording.md) to propose or check text in the review sheet. You do not need to change YAML, JSON or platform files. Ask the guardian to resolve disagreements. + +**Move on when:** the technical volunteer can show what was applied, what remains empty, the preview/build findings and evidence that production remains excluded. A copied English value or empty scaffold does not count as translated wording. Record incomplete checks explicitly rather than hiding them. + +## 4. Make work visible early + +**Technical volunteer and maintainer:** use [save and submit](validation.md#save-and-submit-the-reviewed-change) to open a draft PR after the initial coherent change is locally checked. Describe it as website/scaffold work if guide bodies are still empty. Link the agreed scope and report outstanding findings honestly. + +**Maintainer:** arrange the actual canary according to site delivery policy. A fork PR may run checks without producing a deployed site. Tell reviewers where they can inspect the change; workflow approval does not override a caller that disables deployment. + +**Move on when:** the PR and review arrangement are clear. A missing canary remains a maintainer-owned blocker for the intended canary review; it does not authorise a deployment workaround or imply that production is approved. + +## 5. Translate one selected guide edition + +**Technical volunteer:** select the actual guide/edition/language through discovery and follow [translate a guide](translate-guide.md). Capture the exact source used, prepare a separate candidate, run its checks, and retain the reviewed source/target hashes for application. Use the complete Core examples linked from that task; they are the command route for people without an assistant too. + +With an assistant: + +> Use guide.transcreate for the body of GUIDE, EDITION into LANGUAGE, using our glossary and recorded editorial decisions. Work section by section if helpful. Present source and proposed wording for human review, preserve structural markup and other editions, and report meaning questions. Use the installed candidate checks and reviewed hashes before applying agreed text. + +**Translators and reviewers:** check each passage against its source and glossary. Preserve source meaning and deliberate structure; follow the site's policy for references, names, numbers, adaptation markings and acknowledgement sections. [Review wording](review-wording.md) explains how to give usable feedback. + +**Move on when:** reviewed changes are applied to the selected edition, unresolved questions are visible and the actual diff has been checked. A candidate check does not establish language quality. Repeat this stage only for other editions separately selected by the team. + +## 6. Check what readers will see + +**Technical volunteer:** follow [validation](validation.md) for preview and production builds on the same package. Inspect navigation, language/edition switching, links, fallback and downloads. Apply reviewed corrections through the appropriate [translation update](update-translation.md) or wrapper operation. + +**Team and maintainer:** use [credits and PDFs](credits-pdfs.md) for consented records and eligible downloads. Check representative script shaping, meaningful emphasis, letter spacing, titles and PDF covers on actual rendered artifacts. Proposed font/CSS changes need the responsible maintainer's review; supplied PDFs remain untouched. + +**Move on when:** technical/design findings are resolved and the intended PR/canary review is complete. The maintainer may then merge to preview for the site's native-speaker validation. Reviewers identify the exact preview artifact and give feedback; later corrections still go through PRs. Record what was actually checked, not merely which configuration files exist. + +## 7. Approve publication and keep the translation current + +**Guardian:** approve the wording and completed language review according to site policy. **Maintainer:** separately approve and perform the site's production-promotion/release procedure, check any site-owned issue forms or publication tests affected by the language, and verify the published result. There is no universal one-line release command for every guide site. Permanent production exclusions remain in force. + +Keep the glossary, actual source baseline and useful review decisions for future volunteers. For a later source change, follow [update a translation](update-translation.md) with an explicitly agreed comparison revision. Do not assume the newest source commit is the one previously translated or merge unrelated work just to run a comparison. + +## Handoff checklist + +- [ ] Scope, glossary and applicable site policy are agreed; unresolved decisions are identified. +- [ ] Installed version and valid discovery/Prepare evidence are recorded; failures are accurately labelled. +- [ ] Website text and selected guide bodies have traceable review; empty/protected/fallback states are distinguished. +- [ ] Consented credits and any required acknowledgement are correct; eligible PDFs have receipts and visual review. +- [ ] Preview and production checks, rendered review and actual artifact/revision are recorded. +- [ ] Technical and language findings are resolved or explicitly block the next decision. +- [ ] Production promotion has its own approval and maintainer action; it is not inferred from these ticks. + +Tick only completed work. This checklist records the team's evidence; it is not a new permission mechanism or a replacement for the installed operations. diff --git a/system/OpenGuidePlatform.Agents.Integration/contributor-guide/review-wording.md b/system/OpenGuidePlatform.Agents.Integration/contributor-guide/review-wording.md new file mode 100644 index 0000000..853beb8 --- /dev/null +++ b/system/OpenGuidePlatform.Agents.Integration/contributor-guide/review-wording.md @@ -0,0 +1,47 @@ +# Translate or review wording without running commands + +You can contribute language knowledge without installing developer tools. Ask the technical volunteer for the source text, a review sheet, the agreed glossary and, when available, the link to the rendered candidate. They operate OGP and apply agreed text; you focus on what readers will understand. + +## Ask for a useful review sheet + +The technical volunteer uses discovery to identify the actual files and selected fields. They can prepare a Markdown table or spreadsheet, with or without an assistant. Blank proposed-translation cells are useful when humans are drafting; generated proposals remain proposals. + +Include this context above the table: + +| Context | What the technical volunteer records | +|---|---| +| Scope | Target language/variant, website areas or selected guide/edition | +| Source | Actual file and revision or content hash used for this review | +| Candidate | Candidate identifier/hash and the target hash, or that a target is new | +| Decisions | Agreed glossary and applicable editorial-policy links | +| Rendered review | Artifact/revision and review URL when available; otherwise say unavailable | + +Use one row per field or passage, retaining enough surrounding text to understand its meaning: + +| Row | Source path and field/section | Source wording | Proposed translation | Reviewer feedback | Resolution | +|---|---|---|---|---|---| +| A1 | Actual discovered location | Actual source text | Human or assistant proposal | Suggested correction and reason | Proposed / agreed / unresolved | + +This is a template, not an inventory or import format. The technical volunteer supplies actual paths and hashes. Reviewers do not need to calculate hashes or fill in technical identifiers. An agreed row records a wording decision; supported OGP checks still precede its application. Keep unconsented personal information and private discussions out of public sheets. + +With an assistant, the technical volunteer can ask: + +> Prepare a review sheet for our selected website text or guide passages. Use actual discovery and source/candidate evidence. Include source path and field/section, source wording, proposed translation, reviewer feedback and resolution. Preserve surrounding context. Do not invent approvals, identities, hashes or readiness. Do not apply changes just because a sheet exists. + +## Give feedback the volunteer can apply + +Read for meaning, missing text, terminology, tone and natural word order. Suggest the replacement wording and explain the reason. For example: “A1: use the glossary term for a work item; the current wording means a whole project.” Mark a question as unresolved when the source or intended term is unclear. Do not silently settle a guardian decision or overwrite a conflicting reviewer comment. + +For website messages, preserve placeholders such as `{{ .Site.Title }}` and `{count}`, links and machine identifiers. You may propose a different word order around placeholders. If separate fragments cannot form a natural sentence in your language, flag a template defect rather than accepting misleading wording or editing software identifiers. + +For guide passages, preserve references, links, headings, lists, anchors, shortcodes and intentional emphasis. Confirm the site's rules for reserved terms, licences, references, acknowledgements and change history; another language is not authority for those decisions. + +Use the rendered review when available: check the actual homepage and guide, narrow/wide layouts, reading direction, shaping and meaningful typography. For PDFs, inspect pages rather than assuming an installed font makes them correct. Identify the page/section and artifact with each rendering finding. A screenshot can help locate a problem but does not approve the whole translation. + +## Hand back feedback and check the correction + +Return the completed sheet through the agreed site review channel. Written, audio or video feedback can be used when site policy permits; the technical volunteer should trace each finding to its row/passage. The guardian resolves conflicts. + +The volunteer applies only agreed wording through supported wrapper or guide-translation operations, using the original reviewed hashes. If source or target changed, they reconcile and request renewed review for affected text. An old sheet is not permission to overwrite newer work. + +Ask for a result showing applied rows, unchanged rows, unresolved questions and failed/unsupported operations, followed by the new rendered artifact. Inspect your corrections there. Review approval, completed automation and permission to publish are separate decisions: follow [validation and publication](validation.md). diff --git a/system/OpenGuidePlatform.Agents.Integration/contributor-guide/setup.md b/system/OpenGuidePlatform.Agents.Integration/contributor-guide/setup.md new file mode 100644 index 0000000..fcc9278 --- /dev/null +++ b/system/OpenGuidePlatform.Agents.Integration/contributor-guide/setup.md @@ -0,0 +1,77 @@ +# Set up your computer + +The goal is to open a working copy of the guide site and run its installed tools. Translators who only supply wording or review a web page can work with a technical volunteer instead of installing everything themselves. + +## Prepare access and tools + +1. Read the site's contribution instructions. Agree the work and identify the maintainer or translation guardian who can answer questions. +2. Create a GitHub account. Use GitHub's Fork button on the site's repository if its contribution policy calls for a fork. A fork is your GitHub copy; a clone is the copy on your computer. +3. Follow the site's setup instructions to install Git, PowerShell 7.4 or later, Hugo Extended, Go and the GitHub CLI. The site's requirements may exceed the platform minimums. PDF generation needs additional tools only when you reach that task. +4. Open PowerShell: on Windows use PowerShell 7, rather than Windows PowerShell 5.1. On macOS or Linux, open Terminal and type `pwsh`. All subsequent command blocks marked PowerShell run inside that session. + +## Know where to paste things + +Use two different inputs: commands go into the PowerShell terminal; requests beginning “Use guide…” go into your assistant's conversation. Follow prompts in the terminal when a command such as `Read-Host` asks for a value. Do not paste the surrounding prose or the three backticks that mark a code block. Run one command at a time and read its result before continuing. + +On a Mac, Terminal normally starts another shell, often zsh. Typing `pwsh` starts PowerShell inside it; you can then use the shared command examples unchanged. If `pwsh` is not found, complete PowerShell installation and restart Terminal first. You do not need a separate set of Mac translation procedures. + +Words such as LANGUAGE, GUIDE and EDITION in assistant requests are placeholders: replace them with the agreed values before sending. Do not type angle-bracket placeholders into a shell. In command examples, quoted sample identifiers such as `'your-guide'` also need replacement with discovered identifiers. Paths with spaces belong inside quotes. Do not run `guide.transcreate` as a terminal command; it names assistant instructions. + +## Install and check the tools + +If the site's instructions only list prerequisites, use these official installation pages. Choose your operating system and meet the site's version requirements; you do not need to install an AI assistant. + +| Tool | Installation instructions | Why it is needed | +|---|---|---| +| Git | [Windows, macOS or Linux](https://git-scm.com/install/) | Clone and review repository changes | +| PowerShell | [Windows, macOS or Linux](https://learn.microsoft.com/en-us/powershell/scripting/install/install-powershell) | Run OGP's commands | +| Hugo | [Choose your operating system](https://gohugo.io/installation/) and Extended support | Render the website | +| Go | [Download and install](https://go.dev/doc/install) | Resolve Hugo modules | +| GitHub CLI | [Install GitHub CLI](https://cli.github.com/) | Restore release assets where authenticated access is required | + +Restart your terminal after installing tools so it sees their command paths. To sign the GitHub CLI in, run `gh auth login` and follow its prompts; see [official authentication help](https://cli.github.com/manual/gh_auth_login). Never paste credentials into a review document or assistant conversation. + +Check each tool, one line at a time: + +```powershell +git --version +pwsh --version +hugo version +go version +gh --version +gh auth status +``` + +Expect version output, Hugo reporting Extended support, and the GitHub CLI reporting an authenticated account with the required release access. If a command is missing or access fails, fix that prerequisite before building. Use your site's documented installation instructions; do not guess package names or install a different platform version to get past an error. + +## Get your working copy + +On Windows, enable Developer Mode or obtain equivalent symbolic-link privileges before cloning. OGP uses symbolic links for the shared contributor/agent instructions; ordinary files containing link targets are not a working substitute. The clone command below enables `core.symlinks` for this repository without changing your global Git configuration. If Windows refuses to create links, stop and resolve the prerequisite with your maintainer. + +On your fork's GitHub page, or the site repository when direct contributions are allowed, use Code to copy its HTTPS clone URL. Run: + +```powershell +$repositoryUrl = Read-Host 'Paste the agreed repository HTTPS clone URL' +git clone -c core.symlinks=true $repositoryUrl +``` + +Git prints the directory it created. Enter it using that actual directory name: + +```powershell +$cloneDirectory = Read-Host 'Enter the directory Git created (or its full path)' +Set-Location -LiteralPath $cloneDirectory +Get-Location +git status +``` + +The displayed location should be the guide-site folder, containing `build.ps1` and `.OpenGuidePlatform`. `git status` should identify that repository and show a clean working tree. Follow the site's branch naming and approval rules before making changes. Once the maintainer has agreed a branch name and authorised its creation, `git switch -c` with that name creates it; for an already existing branch, follow their instructions rather than creating another. Do not create a second checkout inside another repository. + +On Windows, also confirm `git config --get core.symlinks` prints `true` and inspect `AGENTS.md` and `CLAUDE.md` with `Get-Item`: they should be symbolic links. A clean `git status` alone does not prove links were checked out correctly. Ask the maintainer to help repair an existing incorrectly checked-out clone while preserving your work. + +From that root folder, follow [check translation status](status.md) to resolve the installed package and run your first assessment. Success means you can identify the installed version and locate the Prepare report, even if that report identifies content work still needed. + +## With an assistant + +Ask: “Read this site's contributor instructions. Check the required tools, repository location and installed OGP version. Explain missing prerequisites before making changes.” Paste this into the assistant's conversation, not the terminal. You do not need an AI subscription to use the manual route. + +**If blocked:** [troubleshooting](troubleshooting.md). **Technical reference:** [installed module loading](../../OpenGuidePlatform.PowerShell.Core/README.md#load-the-installed-commands-and-discover-content). diff --git a/system/OpenGuidePlatform.Agents.Integration/contributor-guide/status.md b/system/OpenGuidePlatform.Agents.Integration/contributor-guide/status.md new file mode 100644 index 0000000..26333e0 --- /dev/null +++ b/system/OpenGuidePlatform.Agents.Integration/contributor-guide/status.md @@ -0,0 +1,32 @@ +# Check translation status + +This assessment answers “what work remains?” without editing site content. First complete [setup](setup.md). Run from the guide-site root in PowerShell: + +```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" +$output = '.processing/translation-status/' + [guid]::NewGuid().ToString('N') +./build.ps1 -Stage Prepare -Target preview -OutputPath $output -PlatformSource Path -PlatformPath $platform +``` + +The unique output name prevents overwriting earlier evidence. Open `$output/prepare/assessment.md` in your editor. Record the installed version and report path. Inspect reports even when Prepare fails, if they exist. A missing report is unknown evidence; a failed assessment is not a pass. + +When discovery produced a valid `discovered-site.json`, inspect the requested language: + +```powershell +$policy = Import-GuidePolicy -Path "$output/discovered-site.json" +$language = Read-Host 'Enter the agreed language code' +$siteWork = Get-GuideSiteTranslationWork -WorkspaceRoot $workspace -Policy $policy -Language $language +$siteWork.Configuration | Format-List +$siteWork.Wrappers | Format-Table Kind, SourcePath, TargetPath, State, SupportedOperation -Wrap +$siteWork.Guides | Format-Table GuideId, EditionId, State, Intent, CanCreateScaffold -Wrap +$siteWork.Findings | Format-List +``` + +Read configuration and website work separately from guide bodies. A proposed target path is not a created file. An empty scaffold is not a translation. Fallback means readers use another declared language; PDF-only means a download exists without equivalent web text. Preserve those deliberate states. “Unsupported” requires a maintainer/platform decision, not an improvised write. + +With an assistant: “Use guide.transstatus for LANGUAGE. Report the installed version, Prepare evidence, site-language work and guide-body work separately. Do not edit. Explain the next action and blockers.” + +**Success:** you can identify each finding's owner and the next supported action. It does not prove language quality or complete rendering. **Next:** [add a language](add-language.md), [translate a guide](translate-guide.md) or [troubleshoot](troubleshooting.md). **Reference:** [Core site-first procedure](../../OpenGuidePlatform.PowerShell.Core/TranslationReadiness/README.md). diff --git a/system/OpenGuidePlatform.Agents.Integration/contributor-guide/system.md b/system/OpenGuidePlatform.Agents.Integration/contributor-guide/system.md new file mode 100644 index 0000000..cc072ba --- /dev/null +++ b/system/OpenGuidePlatform.Agents.Integration/contributor-guide/system.md @@ -0,0 +1,19 @@ +# How the system fits together + +OpenGuidePlatform (OGP) supplies shared building and publishing tools. A guide site owns its content, design choices and publication decisions. Your computer holds a working copy of that site's repository, called a clone. + +![OGP supplies tools to the local clone; reviewed site changes travel through a pull request to the site repository.](diagrams/ownership.svg) + +In words: the installed OGP package supplies commands and matching instructions. You use those commands against the local site files. You submit the reviewed changes to the site's repository through a pull request. Site maintainers decide when those changes reach readers. + +| Owner | What belongs there | +|---|---| +| OGP | Reusable procedures, commands, validation, shared templates and these diagrams | +| Guide site | Guide content, wrapper design, editorial rules, guardian contacts and delivery configuration | +| Translation team | Proposed text, glossary decisions and review findings | + +The wrapper is the website around a guide: homepages, navigation, buttons, history and translation listings. Translating a guide body alone does not translate that experience. A site may have any number of guides and editions. + +Build output goes under `.processing` and is temporary. Do not commit it or edit downloaded platform files. Platform fixes belong in OGP; maintainers adopt a released fix through the coordinated update procedure. + +**Next:** [set up your computer](setup.md), or [choose a task](README.md). diff --git a/system/OpenGuidePlatform.Agents.Integration/contributor-guide/translate-guide.md b/system/OpenGuidePlatform.Agents.Integration/contributor-guide/translate-guide.md new file mode 100644 index 0000000..a4130dd --- /dev/null +++ b/system/OpenGuidePlatform.Agents.Integration/contributor-guide/translate-guide.md @@ -0,0 +1,17 @@ +# Translate a guide + +Choose one guide, edition and language explicitly. Adding the site language is a prerequisite; it does not mean every historical edition must be translated. Use [status](status.md) to discover actual identifiers and preserve existing protected or PDF-only publications. + +## Prepare, review and apply + +Follow [select a guide body](../../OpenGuidePlatform.PowerShell.Core/TranslationReadiness/README.md#select-a-guide-body-for-a-separate-translation-stage), then its candidate/check/application examples. Start from the existing target; create an eligible empty target through the documented operation only when absent. Record the actual source used. + +Translate agreed text using the glossary. Preserve headings, links, references, explicit anchors, shortcodes and meaningful formatting. Read the site's rules for adaptation markers and acknowledgements. The standard translated-document operation permits changes to `title`, `description` and `summary`; other custom metadata needs separate supported review. Do not add `lang` or copy another guide's metadata conventions. + +Use the same [review sheet and handoff](review-wording.md) as website wording. Work section by section when that helps reviewers, retaining the actual source and candidate evidence. The technical volunteer handles command inputs and hashes; translators can focus on text. Source conventions, licence wording and translator sections come from the site's policy and explicit guardian decisions, not an assumed copy of another translation. + +Run `Test-GuideTranslation` on the candidate. `blocked` means a constraint failed. `review-required` means people must still assess meaning; it is not approval. Compare source and candidate outlines and investigate findings. Have reviewers identify omissions, awkward wording and terminology conflicts before applying with the original source and target hashes. + +With an assistant: “Use guide.transcreate to translate GUIDE, EDITION into LANGUAGE using our glossary and the installed procedure. Prepare a candidate, present questions and check findings, and use reviewed hashes before applying. Preserve other editions.” + +**Success:** reviewed wording is applied to the intended document only, the diff agrees with scope, and [build and visual checks](validation.md) are recorded. Native speakers still establish language quality. **If hashes changed:** reconcile your candidate with the new files; never just replace the expected hash. **Next:** [credits/PDFs](credits-pdfs.md), then [review](validation.md). diff --git a/system/OpenGuidePlatform.Agents.Integration/contributor-guide/translation.md b/system/OpenGuidePlatform.Agents.Integration/contributor-guide/translation.md new file mode 100644 index 0000000..b5d32e5 --- /dev/null +++ b/system/OpenGuidePlatform.Agents.Integration/contributor-guide/translation.md @@ -0,0 +1,23 @@ +# Translation journey + +The goal is a complete reader experience whose wording people have reviewed. The guardian decides editorial questions; translators propose wording; reviewers check it; a technical volunteer operates commands; maintainers arrange review environments and publication. One person may have several roles. + +For a practical step-by-step handoff, follow [your first translation](first-translation.md). Translators and reviewers who do not run commands can start with [review wording](review-wording.md). + +![Agree scope, assess the site, add the site language, translate selected guide editions, review and validate, then obtain separate publication approval.](diagrams/translation.svg) + +In words: agree people and terminology, inspect the actual site, introduce the language around the guides, then translate separately selected guide editions. Review rendering and language, resolve feedback, and obtain publication approval. Keep the new language excluded from production throughout preparation. + +## Before translating sentences + +Agree language and regional variant, guide editions, reviewers and the person who resolves disagreements. Build a glossary. Discuss conventions that may not survive translation: meaningful capitals, adaptation italics, reading direction and fonts. Record unresolved choices rather than letting software decide them. Follow the site's rules for licences, acknowledgements, consent and minimum reviewer counts; these are not universal OGP rules. + +Use the [translation playbook](../translation-playbook.md) for team handoffs and scoped assistant requests. Then follow: + +1. [Assess readiness](status.md). +2. [Add the site language](add-language.md), leaving guide bodies for the next stage. +3. [Translate selected guides](translate-guide.md). +4. [Record credits and prepare eligible PDFs](credits-pdfs.md). +5. [Validate and submit](validation.md). + +An optional `docs/translations/LANGUAGE/` folder in the site can retain the glossary, proposed/agreed decisions, source revisions and review notes. Link actual approvals and identify the exact candidate or rendered artifact. These notes are context, not an inventory or automatic permission to publish. Later use [reconciliation](update-translation.md). diff --git a/system/OpenGuidePlatform.Agents.Integration/contributor-guide/troubleshooting.md b/system/OpenGuidePlatform.Agents.Integration/contributor-guide/troubleshooting.md new file mode 100644 index 0000000..77e76b9 --- /dev/null +++ b/system/OpenGuidePlatform.Agents.Integration/contributor-guide/troubleshooting.md @@ -0,0 +1,36 @@ +# Troubleshooting and glossary + +Read the first actionable failure and its report before retrying. Share the command, installed OGP version, report path and relevant error with the maintainer. Omit credentials, private conversations and raw assistant logs. A failed or missing check stays failed/unknown until verified again. + +| Symptom | What to do | +|---|---| +| `./build.ps1` gives shell syntax errors or permission denied | In macOS/Linux Terminal, start `pwsh`, then run the PowerShell instructions from the repository root. | +| Tool is not found | Complete the site's setup, restart the shell if needed and check its version. | +| Release cannot be restored | Check network access, `gh auth status` and access to the selected release. Do not switch OGP versions to bypass it. | +| Output directory already exists | Choose a fresh `.processing` directory; status examples use a unique identifier. Preserve earlier evidence. | +| Prepare fails | Read `prepare/assessment.md` if present. Valid discovery can support repairs; absent/invalid discovery blocks dependent operations. | +| Command or playbook is missing | Report the installed version and missing capability. Maintainers use coordinated Update on a review branch. | +| Stale hash | Reread source/target, reconcile the candidate and review again. Do not just refresh the hash. | +| JSON schema reconciliation is unsupported | Report the path and schema change. Text selection cannot add/remove keys or change structure. | +| A translation shows English | Check declared fallback, actual populated text and Prepare findings. English is not proof of complete translation. | +| Missing interface labels | Check effective catalogue findings and rendered output. Preserve placeholders; report sentence-fragment composition to OGP. | +| No PR canary link | Ask the maintainer to check delivery policy, caller configuration and access. Do not invent a deployment workaround. | +| Broken script rendering or stale PDF receipt | Use the explicit PDF/font workflow and human visual review; preserve supplied PDFs. | + +## Words you will see + +| Word | Meaning | +|---|---| +| Repository / fork / clone | Shared file history / your GitHub copy / your local copy | +| Branch / commit / PR | A line of work / saved snapshot / request to review and merge changes | +| Edition | One version of a guide, independently translated | +| Wrapper / i18n | Website around the guides / interface-message catalogue | +| Front matter | Page settings before its Markdown body | +| Candidate / hash | Proposed replacement / fingerprint of exact reviewed bytes | +| Prepare / discovery | Assessment stage / its generated inventory of the actual site | +| Scaffold / fallback | Empty translation starting point / use of another declared language | +| Canary / preview / production | PR review environment / pre-publication review / public reader environment | +| Guardian | Person authorised by the site to resolve translation editorial decisions | +| Receipt | Recorded evidence tying a generated PDF to inputs and generation conditions | + +**Next:** return to [your task](README.md). Shared command/template defects belong in OGP; editorial decisions, wrapper design and delivery arrangements belong with site maintainers. diff --git a/system/OpenGuidePlatform.Agents.Integration/contributor-guide/update-translation.md b/system/OpenGuidePlatform.Agents.Integration/contributor-guide/update-translation.md new file mode 100644 index 0000000..276c87a --- /dev/null +++ b/system/OpenGuidePlatform.Agents.Integration/contributor-guide/update-translation.md @@ -0,0 +1,13 @@ +# Update a translation + +Reconciliation compares source changes with an existing translation so useful translated passages survive. Start with [setup and discovery](status.md), select the exact guide/edition/language, and agree the comparison revision. A populated translation or recent date does not prove which source it used. + +Follow [Core reconciliation](../../OpenGuidePlatform.PowerShell.Core/TranslationReadiness/README.md#reconcile-against-source-changes). Supply the explicit source commit, and the old source path if it moved. Read the historical/current source diff alongside the current translation. If the baseline is unknown, record that uncertainty and agree a comparison point with the guardian; do not invent provenance. + +Start your candidate from the current translated file. Address changed passages and reviewed feedback, preserve good text, and raise conflicting reviewer requests. Then check the candidate and apply with reviewed current source and target hashes. The recorded comparison is evidence of what was compared, not proof that every difference was translated. + +With an assistant: “Use guide.transreconcile for GUIDE, EDITION and LANGUAGE against SOURCE_COMMIT. Show source changes and proposed corrections first. Preserve useful translated passages and report conflicting feedback. Apply only the agreed scope using the installed checks.” + +**Success:** reviewers can trace findings to corrections or explicit unresolved questions, and the [rendered result and builds](validation.md) have been checked. A translation typo still uses the translated-document writer; source-language corrections use [content changes](content.md). + +**If comparison fails:** check that the commit and historical path exist locally. Ask the maintainer about fetching the needed history; do not silently merge unrelated upstream work or choose a different baseline. diff --git a/system/OpenGuidePlatform.Agents.Integration/contributor-guide/validation.md b/system/OpenGuidePlatform.Agents.Integration/contributor-guide/validation.md new file mode 100644 index 0000000..637e910 --- /dev/null +++ b/system/OpenGuidePlatform.Agents.Integration/contributor-guide/validation.md @@ -0,0 +1,79 @@ +# Validate, review and publish + +Validation checks that the site builds and behaves as intended. People approve wording and publication. Start with the reviewed candidate applied and its actual diff inspected. Use the same installed package as [Prepare](status.md). + +## Check locally + +From the site root in the same PowerShell session: + +```powershell +./build.ps1 -Target preview -PlatformSource Path -PlatformPath $platform +./build.ps1 -Target production -PlatformSource Path -PlatformPath $platform +``` + +Require successful exit codes and inspect reports; explain warnings and resolve errors. A production build checks the production output without publishing. Confirm the new language is excluded there. Use the output paths printed by the build to find reports and rendered files; do not assume an old artifact belongs to this change. + +For interactive local inspection, the site development server is: + +```powershell +./build.ps1 -Stage Serve -Target local +``` + +Open its printed address and stop it with Ctrl+C when done. A development server does not replace the two full builds. Inspect homepage/navigation, language and version switching, history, fallback, links, downloads, narrow/wide layouts and representative script rendering. Check any generated PDF separately. Record the revision or exact candidate, package version, target and artifact inspected. + +## Share reviewed work + +![Local checks lead to a pull-request canary for technical review, preview for language review, and production only after separate approval.](diagrams/publication.svg) + +In words: local checks precede a PR. A maintainer arranges the canary for technical/design review. After technical review, merge to preview for native-speaker validation. Resolve later corrections through PRs, then obtain guardian approval and a separate production-promotion decision. Actual deployment depends on the site's configured workflow and access. + +Review `git status` and `git diff`; stage only intended source files and approved artifacts. Follow the site's commit/push permissions and PR instructions. Include scope, source/candidate revisions, build results, review findings, consented credits and remaining issues. Never commit `.processing` output. Ask maintainers for the review link if fork PRs cannot deploy; approval alone cannot override a disabled deployment caller. + +With an assistant: “Run the required local checks on this exact change. Report evidence, failures and unreviewed wording separately. Prepare a PR description; follow the site's permissions for commits, pushes and publication.” + +## Save and submit the reviewed change + +The technical volunteer performs these actions after the site's required checks/review and Git authorisation. A commit saves locally; push shares it; a PR requests review. Translators who only supply text do not need to run them. + +First inspect the branch and changes: + +```powershell +git branch --show-current +git status --short +git diff +``` + +Confirm the branch is the agreed task branch. Stop if it changed unexpectedly. Check every changed file against scope. `git diff` shows tracked edits; open new files listed by status separately. Do not include `.processing`, credentials or unrelated work. Reviewed generated PDFs/receipts are included only when explicitly part of this task; supplied/protected PDFs stay unchanged. + +Select one intended repository-relative file at a time, then review the whole staged change: + +```powershell +$reviewedPath = Read-Host 'Enter one reviewed file path to include' +git add -- $reviewedPath +git diff --cached +git status --short +``` + +Repeat selection only for additional intended files. If the staged diff is wrong, stop and correct the selection before committing. When it is correct and committing is authorised: + +```powershell +$commitMessage = Read-Host 'Enter a short description of this reviewed change' +git commit -m $commitMessage +git status --short --branch +``` + +Confirm Git reports a successful commit and account for anything still uncommitted. If a hook or command fails, report it and resolve the cause; do not bypass checks. When pushing is authorised under the site's rules, verify that `origin` is the expected fork or repository and that the current branch is still the agreed task branch: + +```powershell +git remote -v +git branch --show-current +$agreedBranch = Read-Host 'Enter the agreed task branch name shown above' +if ((git branch --show-current) -cne $agreedBranch) { throw 'Branch changed; stop and check with the maintainer.' } +git push -u origin $agreedBranch +``` + +Open the site's GitHub repository in your browser and choose the option to create a pull request from the pushed branch. Select the intended destination repository/base branch and your fork/task branch as the comparison. Review the displayed changed files, link the agreed discussion and include the validation evidence and unresolved questions. Select a draft PR while work or review is still in progress. Do not create another PR if the task already has one; subsequent pushes update it. Follow the site's contribution agreement and review requirements when GitHub requests them. + +Success here is a PR that shows the intended changes and their actual status. A draft PR can make website/scaffold work visible before guide bodies are translated; say so explicitly. Maintainers then arrange canary/preview review. Creating a PR does not merge it or publish a release. + +**Success:** checks and human decisions are traceable to the reviewed revision. Passing automation, preview availability and an assistant report are not publication approval. **If a check fails:** use [troubleshooting](troubleshooting.md), retain the failure and rerun affected checks after correction. diff --git a/system/OpenGuidePlatform.Agents.Integration/instructions/guide-site.md b/system/OpenGuidePlatform.Agents.Integration/instructions/guide-site.md index c244cde..04696fc 100644 --- a/system/OpenGuidePlatform.Agents.Integration/instructions/guide-site.md +++ b/system/OpenGuidePlatform.Agents.Integration/instructions/guide-site.md @@ -27,3 +27,5 @@ These instructions guide Codex, Claude and GitHub Copilot; they do not enforce p 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. + +For human-facing setup, translation/content tasks, review and troubleshooting with SVG diagrams, open system/OpenGuidePlatform.Agents.Integration/contributor-guide/README.md in the resolved installed package. Guide-site entry pages should link to the matching OGP source revision and retain local editorial/delivery policy rather than copy shared procedures. diff --git a/system/OpenGuidePlatform.Agents.Integration/skills/USAGE.md b/system/OpenGuidePlatform.Agents.Integration/skills/USAGE.md index 2725f7e..cd95e7c 100644 --- a/system/OpenGuidePlatform.Agents.Integration/skills/USAGE.md +++ b/system/OpenGuidePlatform.Agents.Integration/skills/USAGE.md @@ -60,3 +60,5 @@ For the team journey, review handoffs and context-rich skill requests, follow `s ```powershell Get-Content "$platform/system/OpenGuidePlatform.Agents.Integration/translation-playbook.md" ``` + +In the resolved installed package, open `system/OpenGuidePlatform.Agents.Integration/contributor-guide/README.md` for human-facing setup, task explanations and SVG diagrams. The same pages are browsable in OGP at the package source commit. Keep site-specific policy in the consumer repository. diff --git a/system/OpenGuidePlatform.Agents.Integration/translation-playbook.md b/system/OpenGuidePlatform.Agents.Integration/translation-playbook.md index 14e8a18..7882b12 100644 --- a/system/OpenGuidePlatform.Agents.Integration/translation-playbook.md +++ b/system/OpenGuidePlatform.Agents.Integration/translation-playbook.md @@ -69,3 +69,5 @@ These notes are reference material, not executable instructions, runtime invento ## Report gaps to the correct owner Shared command, skill, template and rendering defects belong in OGP. Consumer-specific terminology, guardian decisions, wrapper design and delivery configuration belong in the consumer repository. Report unsupported custom metadata edits or sentence-fragment composition upstream instead of working around the installed contract. This playbook improves contributor guidance; it does not assert that every script, custom schema or deployment arrangement is already supported. + +For setup, plain-English task explanations and diagrams, use the [contributor guide](contributor-guide/README.md). This playbook retains the shared team journey and handoffs. diff --git a/system/OpenGuidePlatform.PowerShell.Core/README.md b/system/OpenGuidePlatform.PowerShell.Core/README.md index 5c06ed2..e34c5a6 100644 --- a/system/OpenGuidePlatform.PowerShell.Core/README.md +++ b/system/OpenGuidePlatform.PowerShell.Core/README.md @@ -135,3 +135,5 @@ For a permanent guide or edition exclusion, declare `artifactPrefixes` alongside Existing legacy aliases may be recorded in `wrapper.legacyAliases`: exact source file, language, legacy alias values and observed output targets. Prepare rejects new or missing declarations, and Validate permits only their matching duplicate output counts. This preserves existing `/download/`, `/downloads/` and `/translationsdirectory/` compatibility without assigning a new owner or extending it to new languages. Other aliases and duplicate routes receive no exemption. Populate this record from the existing site during adoption; the platform does not add aliases. + +For plain-English explanations and diagrams before these command examples, start with the [contributor guide](../OpenGuidePlatform.Agents.Integration/contributor-guide/README.md). diff --git a/system/OpenGuidePlatform.PowerShell.PlatformBuild/Packaging/Test-OpenGuidePlatformPackage.ps1 b/system/OpenGuidePlatform.PowerShell.PlatformBuild/Packaging/Test-OpenGuidePlatformPackage.ps1 index 8c29afb..7ed4c7a 100644 --- a/system/OpenGuidePlatform.PowerShell.PlatformBuild/Packaging/Test-OpenGuidePlatformPackage.ps1 +++ b/system/OpenGuidePlatform.PowerShell.PlatformBuild/Packaging/Test-OpenGuidePlatformPackage.ps1 @@ -23,6 +23,7 @@ try { if(-not [IO.File]::Exists((Join-Path $destination $path))){throw "Package missing $path"} } if(Test-Path "$destination/bootstrap.ps1"){throw 'Remote bootstrap must not be installed in a package.'} + & "$PSScriptRoot/../Testing/Test-ContributorDocumentation.ps1" -PackageRoot $destination # Importability must not replace the caller's live modules with temporary copies. & (Get-Process -Id $PID).Path -NoProfile -Command { param($package) diff --git a/system/OpenGuidePlatform.PowerShell.PlatformBuild/Testing/Test-ContributorDocumentation.ps1 b/system/OpenGuidePlatform.PowerShell.PlatformBuild/Testing/Test-ContributorDocumentation.ps1 new file mode 100644 index 0000000..d0bce99 --- /dev/null +++ b/system/OpenGuidePlatform.PowerShell.PlatformBuild/Testing/Test-ContributorDocumentation.ps1 @@ -0,0 +1,41 @@ +#Requires -Version 7.4 +[CmdletBinding()] +param([Parameter(Mandatory)][string]$PackageRoot) +$ErrorActionPreference = 'Stop' +$packagePath = [IO.Path]::GetFullPath($PackageRoot) +$guide = Join-Path $PackageRoot 'system/OpenGuidePlatform.Agents.Integration/contributor-guide' +$pages = @('README','system','setup','files','translation','first-translation','review-wording','status','add-language','translate-guide','update-translation','content','credits-pdfs','validation','troubleshooting') +foreach ($page in $pages) { + $path = Join-Path $guide "$page.md" + if (-not (Test-Path -LiteralPath $path -PathType Leaf)) { throw "Contributor documentation missing: $page.md" } + $text = [IO.File]::ReadAllText($path) + # Code examples describe syntax, not navigation links. + $prose = [regex]::Replace($text, '(?ms)^```.*?^```\r?$', '') + $prose = [regex]::Replace($prose, '`[^`\r\n]+`', '') + foreach ($match in [regex]::Matches($prose, '\[[^\]]*\]\(([^)]+)\)')) { + $link = $match.Groups[1].Value + if ($link -match '^[a-z]+:') { continue } + $parts = $link.Split('#', 2) + $target = if ($parts[0]) { [IO.Path]::GetFullPath((Join-Path $guide $parts[0])) } else { $path } + $relativeTarget = [IO.Path]::GetRelativePath($packagePath, $target).Replace('\', '/') + if ([IO.Path]::IsPathRooted($relativeTarget) -or $relativeTarget -match '^\.\.(?:/|$)') { + throw "Contributor link escapes package in ${page}: $link" + } + if (-not (Test-Path -LiteralPath $target -PathType Leaf)) { throw "Broken contributor link in ${page}: $link" } + if ($parts.Count -eq 2 -and $parts[1]) { + $headings = [regex]::Matches([IO.File]::ReadAllText($target), '(?m)^#{1,6} (.+)\r?$') + $anchors = @($headings | ForEach-Object { ($_.Groups[1].Value.Trim().ToLowerInvariant() -replace '[^\p{L}\p{N}_ -]', '') -replace ' ', '-' }) + if ($parts[1] -cnotin $anchors) { throw "Broken contributor anchor in ${page}: $link" } + } + } +} +foreach ($name in @('ownership','candidate','translation','publication')) { + $path = Join-Path $guide "diagrams/$name.svg" + if (-not (Test-Path -LiteralPath $path -PathType Leaf)) { throw "Contributor diagram missing: $name" } + [xml]$svg = [IO.File]::ReadAllText($path) + if ($svg.DocumentElement.LocalName -ne 'svg' -or -not $svg.svg.viewBox -or -not $svg.svg.title.InnerText -or -not $svg.svg.desc.InnerText -or $svg.svg.role -ne 'img' -or $svg.svg.'aria-labelledby' -ne 'title description') { + throw "Contributor diagram lacks accessible structure: $name" + } + if ($svg.SelectNodes('//*[local-name()="script" or local-name()="foreignObject"]').Count -gt 0) { throw "Contributor diagram contains active content: $name" } +} +"Validated contributor pages, local links, heading anchors and SVG structure in $PackageRoot" diff --git a/tests/Core/ContributorDocumentation.Tests.ps1 b/tests/Core/ContributorDocumentation.Tests.ps1 new file mode 100644 index 0000000..b49c768 --- /dev/null +++ b/tests/Core/ContributorDocumentation.Tests.ps1 @@ -0,0 +1,36 @@ +BeforeAll { + $root = Split-Path (Split-Path $PSScriptRoot -Parent) -Parent + $checker = "$root/system/OpenGuidePlatform.PowerShell.PlatformBuild/Testing/Test-ContributorDocumentation.ps1" +} +Describe 'Distributed contributor documentation' { + It 'has complete task navigation, references and accessible SVG structure' { + & $checker -PackageRoot $root + } + It 'rejects a missing page in a distribution' { + { & $checker -PackageRoot $TestDrive } | Should -Throw '*documentation missing*' + } + It 'rejects a broken local reference rather than silently accepting a partial package' { + $fixture = Join-Path $TestDrive 'broken' + $guide = "$fixture/system/OpenGuidePlatform.Agents.Integration/contributor-guide" + [IO.Directory]::CreateDirectory($guide) | Out-Null + Set-Content "$guide/README.md" '[Setup](setup.md)' + { & $checker -PackageRoot $fixture } | Should -Throw '*Broken contributor link*' + } + It 'rejects a missing diagram referenced as a Markdown image' { + $fixture = Join-Path $TestDrive 'missing-image' + $guide = "$fixture/system/OpenGuidePlatform.Agents.Integration/contributor-guide" + [IO.Directory]::CreateDirectory($guide) | Out-Null + Set-Content "$guide/README.md" '![System overview](diagrams/missing.svg)' + { & $checker -PackageRoot $fixture } | Should -Throw '*Broken contributor link*' + } + It 'rejects a link to an existing file outside the package' { + $fixture = Join-Path $TestDrive 'escaping-link' + $guide = "$fixture/system/OpenGuidePlatform.Agents.Integration/contributor-guide" + [IO.Directory]::CreateDirectory($guide) | Out-Null + $outside = Join-Path $TestDrive 'outside.md' + Set-Content $outside '# Outside the distribution' + $relative = [IO.Path]::GetRelativePath($guide, $outside).Replace('\', '/') + Set-Content "$guide/README.md" "[Outside]($relative)" + { & $checker -PackageRoot $fixture } | Should -Throw '*escapes package*' + } +}