[Marius Storhaug (MariusStorhaug)]

The public MSX profile identifies the shared guidance and GitHub community-default context. The agent entry point describes its source documents without an enforcement claim.

Changed: Entry points describe their linked guidance

The profile links MSX documentation and the community-defaults repository. Agent instructions keep the README-then-CONTRIBUTING sequence and describe what those files contain. The brand heading and both wrapper routes remain unchanged. No reader or agent configuration change is required.

---

Technical details

Scope and persistent source

The comparison is 0c67251812ea306543f3a14ab473ae357cfb76ac...e90ab70966ccfa12f7c20a486fb40f5846062c9a. The PR contains only profile/README.md and AGENTS.md: nine added lines and two removed lines. The worktree is clean.

Three small commits retain the implementation sequence:

• ce0a2f3c7646fcbe4d06cb0fa5c857034ba164eb: add profile context and links; open this draft before the agent edit.
• 5b6191d042d48503124cdfcad9a062182be546db: correct both agent read-order descriptions.
• e90ab70966ccfa12f7c20a486fb40f5846062c9a: use file of that type for the default-file explanation after the source-vocabulary review.

The root README, contribution guide, PR template, forms, and SECURITY/SUPPORT policies are not changed. Root README audience clarification remains with its existing owner. No tooling, dependency, generated output, or documentation structure is added.

Source and factual review

The fixed authority is MSXOrg/docs commit 1b0d4893c8fefabe604d04393068a8ff6f848082, under src/docs/. The source review covers Documentation Model, Natural Language, Writing Guide, Markdown, Documentation, README-Driven Context, and the applicable workflow, contribution, PR, commit, branching, and completion guidance.

Changed statement	Verified evidence
MSX documentation contains shared standards and ways of working for humans and agents.	The pinned MSX home page, especially its scope and documentation map.
The community-defaults repository contains shared GitHub files; GitHub uses a default when a repository has no file of that type.	The baseline root README and actual tracked community files.
The root README covers community defaults, MSX documentation, and shared media.	The same baseline README, inspected in the worktree and through GitHub.
CONTRIBUTING links MSX contribution guidance.	The baseline contribution guide, which points to central MSX documentation.

The official STE description, FAQ, and Issue 9 DOI record are available. The local Issue 9 PDF has MD5 9c720341c350ed77943b2c73d01c716f, which matches the official record. The review uses the relevant verb, instruction, descriptive-writing, and dictionary guidance. The manual and extraction remain local.

The added prose uses en-US, present tense, active voice, and short sentences. Its plain-text sentence lengths are 14, 8, and 15 words. Read in this order: remains imperative. Ways of working retains the source's technical term. The existing slogan is an accepted branding difference, not a claimed STE-compliant technical statement. Neither these checks nor a word count establish full STE conformance.

All required pinned MSX and official STE sources are available. The custom instruction's literal parent ..\AGENTS.md path is absent. The repository root AGENTS.md is available, was read, and is the verified destination of both actual wrappers. No source or access blocker prevents this delivery.

Before and after acceptance evidence

The pre-edit record retains the baseline failures. The same 12 acceptance checks return seven passes and five expected failures before editing, then 12 passes and no failures after editing. The final wording is included in the passing run.

Check	Before	After
Profile orientation	Missing; only the slogan exists.	Shared guidance and its human/agent audience are stated.
Canonical documentation link	Missing.	https://msx.no/docs/ is present and returns HTTP 200.
Community-default context and link	Missing.	The repository link and default-file explanation are present; the link returns HTTP 200.
README description	Claims that the README describes enforcement.	Describes community defaults, MSX documentation, and shared media.
Contribution-guide description	Claims that the guide describes change and review steps.	Describes the link to MSX contribution guidance.
Remaining seven route/format/no-change checks	Pass.	Pass without changing the instructions, headings, targets, or protected files.

The exact read order remains README.md, then .github/CONTRIBUTING.md. Both target files exist. Both H1 texts are identical to the baseline, so their existing heading anchors remain stable. No heading or fragment is added.

No-change wrapper	Exact syntax	Resolved target
.claude/CLAUDE.md	@../AGENTS.md	Root AGENTS.md
.github/copilot-instructions.md	Follow the instructions in [AGENTS.md](../AGENTS.md).	Root AGENTS.md

Exact acceptance check

This PowerShell block was run before and after the edit. The baseline exits 1 with five expected failures. The final source exits 0 with 12/12 passed; 0 failed. The text assertions verify explicit content and invariant routes; the source table above supplies the factual review.

$baseline = '0c67251812ea306543f3a14ab473ae357cfb76ac'
$profile = Get-Content -LiteralPath 'profile\README.md' -Raw
$agents = Get-Content -LiteralPath 'AGENTS.md' -Raw
$readOrder = @([regex]::Matches($agents, '(?m)^\d+\. \[[^\]]+\]\(([^)]+)\)') | ForEach-Object { $_.Groups[1].Value })
$profileHeading = [regex]::Match($profile, '(?m)^# .+').Value.TrimEnd()
$baselineProfileHeading = (git show "${baseline}:profile/README.md" | Select-Object -First 1).TrimEnd()
$agentHeading = [regex]::Match($agents, '(?m)^# .+').Value.TrimEnd()
$baselineAgentHeading = (git show "${baseline}:AGENTS.md" | Select-Object -First 1).TrimEnd()
git diff --quiet $baseline -- README.md .github\CONTRIBUTING.md .github\pull_request_template.md .claude\CLAUDE.md .github\copilot-instructions.md
$protectedFilesUnchanged = $LASTEXITCODE -eq 0
$agentPath = (Resolve-Path -LiteralPath 'AGENTS.md').Path
$checks = [ordered]@{
    ProfileOrientation = ($profile -match 'shared standards' -and $profile -match 'ways\s+of working' -and $profile -match '(humans|people) and agents')
    CanonicalDocumentationLink = $profile.Contains('https://msx.no/docs/')
    CommunityDefaultContext = ($profile.Contains('https://github.com/MSXOrg/.github') -and $profile -match 'GitHub uses a default file')
    NoEnforcementClaim = $agents -notmatch '\benforc'
    ContributionPointerDescription = ($agents -match 'link to MSX contribution guidance' -and $agents -notmatch 'made and reviewed')
    ExactReadOrder = (($readOrder -join '|') -ceq 'README.md|.github/CONTRIBUTING.md')
    ReadTargetsResolve = ((Test-Path -LiteralPath 'README.md' -PathType Leaf) -and (Test-Path -LiteralPath '.github\CONTRIBUTING.md' -PathType Leaf))
    ImperativeInstruction = $agents.Contains('Read in this order:')
    HeadingStability = ($profileHeading -ceq $baselineProfileHeading -and $agentHeading -ceq $baselineAgentHeading)
    ThinPointerSyntax = ((Get-Content -LiteralPath '.claude\CLAUDE.md' -Raw).Trim() -ceq '@../AGENTS.md' -and (Get-Content -LiteralPath '.github\copilot-instructions.md' -Raw).Trim() -ceq 'Follow the instructions in [AGENTS.md](../AGENTS.md).')
    WrapperResolution = ((Resolve-Path -LiteralPath '.claude\..\AGENTS.md').Path -ceq $agentPath -and (Resolve-Path -LiteralPath '.github\..\AGENTS.md').Path -ceq $agentPath)
    ProtectedFilesUnchanged = $protectedFilesUnchanged
}
$checks.GetEnumerator() | ForEach-Object { '{0}: {1}' -f $_.Key, $(if ($_.Value) { 'PASS' } else { 'FAIL' }) }
$failed = @($checks.Values | Where-Object { -not $_ }).Count
'{0}/{1} passed; {2} failed' -f ($checks.Count - $failed), $checks.Count, $failed
if ($failed -gt 0) { exit 1 }

Other checks and results

Exact command	Result
git diff --check 0c67251812ea306543f3a14ab473ae357cfb76ac	Passed after both edits and after the final wording change.
git diff --cached --check	Passed before each of the three commits.
git diff --check 0c67251812ea306543f3a14ab473ae357cfb76ac...HEAD	Passed for final commit e90ab70966ccfa12f7c20a486fb40f5846062c9a.
git diff --name-only 0c67251812ea306543f3a14ab473ae357cfb76ac	Returned exactly AGENTS.md and profile/README.md.
git diff --exit-code 0c67251812ea306543f3a14ab473ae357cfb76ac...HEAD -- .claude\CLAUDE.md .github\copilot-instructions.md README.md .github\CONTRIBUTING.md .github\pull_request_template.md	Passed with no diff.
curl.exe --fail --location --silent --show-error --max-time 60 --output NUL --write-out 'HTTP %{http_code}; URL %{url_effective}\n' 'https://msx.no/docs/'	Passed; HTTP 200 at that canonical URL.
curl.exe --fail --location --silent --show-error --max-time 60 --output NUL --write-out 'HTTP %{http_code}; URL %{url_effective}\n' 'https://github.com/MSXOrg/.github'	Passed; HTTP 200 at that repository URL.
git --no-pager status --short	Passed with no output; the worktree is clean.

Both HTTP destinations were also read to confirm the expected content, not only a successful status. The profile uses an absolute repository link so it reaches the same context from both the organization profile and the repository view.

The following GitHub GFM render commands succeed for the final source. Shape assertions confirm one H1, two paragraphs, and two canonical links for the profile; one H1 and one two-step ordered list for AGENTS.md. The wrapper-resolution command returns the same root AGENTS.md for both paths.

$profile = Get-Content -LiteralPath 'profile\README.md' -Raw
$profileHtml = (@{ text = $profile; mode = 'gfm'; context = 'MSXOrg/.github' } | ConvertTo-Json -Compress | gh api --method POST markdown --input -) -join "`n"
$agents = Get-Content -LiteralPath 'AGENTS.md' -Raw
$agentsHtml = (@{ text = $agents; mode = 'gfm'; context = 'MSXOrg/.github' } | ConvertTo-Json -Compress | gh api --method POST markdown --input -) -join "`n"
Resolve-Path -LiteralPath '.claude\..\AGENTS.md', '.github\..\AGENTS.md' | Select-Object -ExpandProperty Path

Markdown/link lint was not run: the baseline has no corresponding scripts, shared Markdown configuration, package manifest, or workflow directory. The availability probe finds no installed markdownlint-cli2, markdownlint, or pymarkdown command. No dependency is installed. Unmerged #12 is not treated as installed or enforced validation.

foreach ($name in @('markdownlint-cli2', 'markdownlint', 'pymarkdown')) { $command = Get-Command -Name $name -ErrorAction SilentlyContinue; if ($null -eq $command) { '{0}: unavailable' -f $name } else { '{0}: {1}' -f $name, $command.Source } }
git ls-files -- '*.ps1' '.github/workflows/*' '*markdownlint*' '*markdown-lint*' 'package.json' 'pyproject.toml'

The probe reports all three commands unavailable. The tracked-file query returns no matches. The local/manual checks above are evidence for this delivery, not installed CI enforcement.

Standards and framework alignment

The final pass checks the applicable pinned process and writing sources against the whole diff. No mission, guarantee, policy, enforcement mechanism, or response promise is added.

Changed surface	Standards checked	Framework docs checked	Result
profile/README.md	Documentation Model, Natural Language, Writing Guide, Markdown, Documentation, README-Driven Context; relevant Issue 9 rules	None (no framework-specific docs). Facts match the pinned MSX home page and repository README.	Aligned; the brand heading is the accepted branding difference in the delivery leaf.
AGENTS.md	Natural Language, Writing Guide, Markdown; ordered and verifiable agent instructions	None (no framework-specific docs). Descriptions match README and CONTRIBUTING.	Fixed in this PR; exact instruction order and paths are preserved.

Convergence, plan, and review

The scoped convergence command is:

gh issue list --repo MSXOrg/.github --state open --search 'documentation-writing-alignment in:title' --limit 25 --json number,title,body,url

It returns delivery leaves #16, #17, and #18. The two-file diff satisfies only #17. The form and reporting-policy asks are not satisfied by this change, so no additional closing reference is added. The native blocked-by query returns an empty list.

The issue plan records source review, small commits, early draft creation, factual and route checks, and validation evidence. This PR carries the final alignment, convergence, and review record.

The explicit command gh pr edit 20 --repo MSXOrg/.github --add-reviewer '@copilot' succeeds after the final push. The final-source review is APPROVED for e90ab70966ccfa12f7c20a486fb40f5846062c9a, with zero inline comments and no active review issues. Its remote review check completed with success. This is a review result, not a Markdown/link CI result.

The PR remains open and draft, assigned to its author. GitHub auto-merge is null; Agent merge is disabled and its merge action is false. No merge or merge-automation change is made. The repository has no versioned producer route in this source tree, so no release decision block or release label is added.

Relevant issues (or links)

Resolves #17.

References MSXOrg/.github#12 for the separate, unmerged Markdown validation work. Its check is not installed on this PR's baseline.

[Copilot]

🟢 Approved

There are no active review issues for these documentation and agent-guidance updates.

No open issues 🎉

What changed in this PR

This prose-only PR gives readers factual context for MSX documentation and GitHub community defaults, and corrects the agent entry-point descriptions.

Changes:

• Adds public-profile orientation and links to MSX documentation and the community defaults repository.
• Updates agent read-order descriptions while preserving the README-then-CONTRIBUTING sequence and paths.
• Preserves the public profile’s brand heading.

File	Description
profile/​README.md	Adds guidance links and explains GitHub’s default-file fallback behavior.
AGENTS.md	Replaces overstated descriptions with accurate summaries of the linked documents.

_{Review effort: Balanced}

[Copilot]

🟢 Approved

No active review issues are recorded for the documentation updates clarifying MSX entry points and shared GitHub community defaults.

No open issues 🎉

_{Review effort: Balanced}