wiki-sync

name	wiki-sync
description	Compiles and maintains `/wiki` as a generated, provenance-aware, cross-linked semantic projection of `/docs`. Supports automatic incremental sync and forced rebuild/lint/repair/consolidation flows. The generated wiki must remain suitable both for agent reasoning and for frontend-rendered onboarding/reference experiences for project newcomers.

Wiki Sync Skill

Purpose

This skill maintains a generated /wiki directory as a semantic projection of the human-authored /docs directory.

/docs is the normative source layer.
/wiki is the compiled interpretation layer.

The agent MUST treat /docs as the authoritative source of truth and /wiki as a maintained derivative artifact optimized for navigation, synthesis, cross-linking, query-time reasoning, and frontend rendering.

The generated /wiki MUST serve two audiences simultaneously:

1. Agents, which need compact, structured, provenance-aware semantic access and graph-shaped navigation for query-time reasoning
2. Human newcomers, which need clear onboarding-oriented explanations, stable navigation, and low-friction discovery of core concepts

The agent MUST optimize wiki output for both machine readability and frontend rendering quality. Token savings are a useful side effect of a compact semantic projection, not the primary objective; the primary objective is truthful, navigable, provenance-aware project exploration.

Core Model

Source Authority

The agent MUST apply the following authority order:

1. /docs authoritative human-authored content
2. Explicit repository metadata relevant to docs/wiki sync
3. Existing /wiki pages as prior generated artifacts
4. Inferred structure generated by the agent

The agent MUST NEVER allow /wiki to override /docs.

The agent MUST NEVER silently preserve a wiki claim that conflicts with updated evidence in /docs.

Layer Semantics

/docs:

• Human-authored
• Normative or primary explanatory content
• Source of truth
• May contain drafts, deprecated pages, or superseded pages
• MUST NOT be rewritten by this skill unless the user explicitly asks for edits to /docs

/wiki:

• Agent-maintained
• Synthesized
• Cross-linked
• Query-optimized
• Frontend-renderable
• Allowed to merge information from multiple docs
• MUST remain traceable back to /docs
• MUST NOT introduce stronger claims than supported by /docs

Semantic Compilation

The agent MUST treat wiki synchronization as semantic compilation rather than mere summarization.

The objective is not to duplicate /docs.

The objective is to maintain a compact, truthful, navigable, provenance-aware, cross-linked knowledge surface aligned with /docs and suitable for both agent use and newcomer-facing UI rendering. A page is valid only when it improves human onboarding, frontend reference navigation, or agent traversal of the project knowledge graph.

Goals

The agent using this skill MUST:

1. Detect meaningful changes in /docs
2. Determine which wiki pages are affected
3. Create or update only the necessary pages in /wiki
4. Preserve provenance for nontrivial claims
5. Maintain compact locale-scoped index entrypoints such as index.en.md and index.<locale>.md
6. Detect contradictions, stale pages, weak pages, duplicate concepts, broken links, and navigation drift
7. Support full rebuild when explicitly requested
8. Keep the wiki legible to both humans and agents
9. Keep the wiki structurally suitable for a frontend knowledge section
10. Avoid epistemic drift between /docs and /wiki
11. Improve newcomer onboarding quality as the docs evolve

Non-Goals

This skill MUST NOT:

• Act as a generic search engine
• Rewrite /docs unless explicitly asked
• Invent unsupported facts
• Silently discard contradictions
• Silently flatten uncertainty into certainty
• Turn /wiki into a second uncontrolled documentation tree
• Require /wiki to exist for the project to function
• Make /wiki part of the build-critical path unless the repository explicitly requires it
• Optimize only for insiders while neglecting newcomer readability
• Emit pages that depend on private conversational context not grounded in /docs

Invocation Modes

Automatic Mode

The agent SHOULD run this skill automatically when one or more files under /docs are added, changed, moved, deprecated, superseded, or deleted.

Automatic mode SHOULD prefer incremental synchronization over full rebuild.

Automatic mode SHOULD update only the affected wiki artifacts unless structural drift, schema drift, or large-scale doc changes make rebuild necessary.

Forced Mode

The agent MUST support explicit forced invocation when the user or caller requests actions such as:

• Sync wiki
• Update wiki
• Refresh wiki
• Rebuild wiki
• Recompile wiki
• Lint wiki
• Consolidate wiki
• Repair wiki
• Regenerate wiki from docs
• Regenerate one page
• Refresh frontend-facing summaries
• Rebuild onboarding pages

Forced mode MAY run even if no changes are detected.

Forced mode MUST obey the specific requested scope if provided.

Examples:

• Sync only changed pages
• Rebuild everything
• Lint only
• Consolidate confidence and supersession
• Repair links and index
• Regenerate one page from selected docs
• Rebuild overview and glossary pages only

Expected Repository Structure

This skill assumes a repository layout roughly like:

.agents/skills/wiki-sync/SKILL.md
/docs/
/wiki/

The skill SHOULD work even if /wiki does not yet exist.

The skill MAY create the following files or directories under /wiki:

/wiki/index.en.md
/wiki/index.<locale>.md
/wiki/_meta/
/wiki/_meta/navigation.json
/wiki/_meta/state.json
/wiki/_meta/graph.json
/wiki/_meta/aliases.json
/wiki/_meta/locales.json

Exact layout MAY vary by repository convention, but the semantic roles MUST remain stable.

Recommended Wiki Layout

A preferred layout is:

/wiki/index.en.md
/wiki/index.<locale>.md
/wiki/overview/
/wiki/getting-started/
/wiki/concepts/
/wiki/entities/
/wiki/processes/
/wiki/decisions/
/wiki/comparisons/
/wiki/glossary/
/wiki/faq/
/wiki/status/
/wiki/timeline/
/wiki/_meta/navigation.json
/wiki/_meta/state.json
/wiki/_meta/graph.json
/wiki/_meta/aliases.json
/wiki/_meta/locales.json

If the repository already has a different wiki layout, the agent SHOULD adapt to the existing structure rather than forcing a migration unless the user explicitly requests restructuring.

Required Artifacts

index.<locale>.md

The wiki MUST contain locale-scoped root entrypoints such as index.en.md and any requested mirrored locales like index.ru.md.

Each index.<locale>.md MUST:

• Remain concise enough for efficient agent use
• Expose the high-level topic structure
• Link to major wiki pages in the same locale when those mirrors exist
• Surface recently changed areas when useful
• Provide discoverable entry paths for newcomers
• Avoid becoming a full duplicate of the wiki contents

The agent SHOULD treat the default-locale index.<locale>.md as the primary navigation surface for compatibility-sensitive consumers, while still keeping locale mirrors aligned.

Delivery History

The wiki MUST NOT maintain separate mutation log files by default.

Completed wiki delivery work belongs in the project-level delivery history, normally CHANGELOG.md, unless a repository explicitly introduces a different canonical history surface.

The wiki may preserve freshness, confidence, provenance, and graph state through _meta/*.json, but those metadata artifacts are not a second changelog.

Locale Mirroring Contract

The wiki MUST treat internationalization as a first-class structural contract rather than an afterthought.

The agent MUST ensure:

• All human-facing wiki markdown files use a locale suffix such as .<locale>.md
• The current default locale is en unless the repository states otherwise
• Non-default locale pages mirror the same page ids and relative path topology as the default locale
• Localized internal links point to localized wiki pages when those mirrors exist
• Localized metadata with user-facing strings or locale-specific paths is stored inside shared JSON manifests through language-keyed objects such as title: { en: ..., ru: ... }
• A locale manifest such as _meta/locales.json exists when the repository needs an explicit supported-locale map

If localized source docs are incomplete, the agent MAY generate a truthful mirror page from the default-locale wiki page, but it MUST mark that page explicitly with metadata such as translation_of and translation_status: mirrored-from-default instead of pretending full source-localized synthesis exists.

Page-Level Provenance

Each nontrivial wiki page MUST reference its supporting doc sources.

This MAY appear in frontmatter, a source section, sidecar metadata, or a combination of those.

Optional Metadata Artifacts

If repository conventions allow, the agent SHOULD maintain:

• navigation.json for localized navigation strings and localized wiki paths stored as language-keyed objects inside one manifest
• state.json for confidence, freshness, staleness, supersession, and other page-level state, with localized fields grouped under language keys where needed
• graph.json for typed relations between pages, with localized node labels and localized page paths grouped under language keys where needed
• aliases.json for canonical naming and alias resolution, with alias maps grouped by language key
• locales.json for supported locales, default locale, and localized page or metadata entrypoints

Frontend Rendering Contract

Because the /wiki directory is used as the content source for a frontend knowledge section, the agent MUST keep the wiki structurally suitable for rendering in a client UI.

The agent MUST prefer:

• Stable titles
• Predictable page categories
• Concise summaries
• Scannable section structure
• Low-noise prose
• Consistent related-links sections
• Glossary-friendly terminology
• Explicit overview pages for major topic areas
• Frontend-safe metadata fields
• Deterministic placement of pages within topic structure

The agent MUST avoid:

• Unstable naming
• Giant unstructured pages
• Excessive internal-only shorthand
• Unresolved placeholder text
• Duplicate pages with near-identical meaning
• Pages that make sense only with hidden context from private discussions
• Inconsistent summary formats
• Deeply nested navigation without overview pages
• Brittle formatting that assumes a specific renderer beyond Markdown basics

The agent SHOULD assume that page titles, summaries, tags, related links, and page types may be consumed directly by frontend code.

Wiki frontmatter is consumed through a simple TOML-like key: value contract. The agent MUST NOT put additional value-side colons on scalar metadata lines such as summary: because downstream parsers treat colons as key/value separators. Rewrite such summaries with dashes, commas, or sentence structure instead of summary: Topic: details.

If the repository renders wiki markdown directly in the browser as trusted repo-local content, the agent SHOULD also keep the emitted markdown inside that trust contract by avoiding raw HTML blocks, dangerous URL schemes, and inline DOM event-handler attributes so repo-level validation (e.g. via scripts/validate-wiki-trust.sh) can stay the primary safety boundary.

Onboarding Requirement

The agent MUST treat newcomer comprehension as a first-class requirement.

For major subsystems or topic clusters, the agent SHOULD maintain at least one of the following:

• Overview page
• Getting-started page
• Glossary page
• Comparison page explaining how related concepts differ
• FAQ page for common newcomer confusions

The agent SHOULD prefer progressive disclosure:

1. Short summary first
2. Core concepts second
3. Details after that
4. Related pages at the end

The agent MUST NOT assume expert-only context in pages intended for general wiki navigation.

When writing for /wiki, the agent SHOULD resolve local shorthand, project-internal abbreviations, and conversation-derived assumptions unless those are already defined in /docs or in the wiki glossary.

Page Taxonomy

The agent SHOULD organize wiki pages into one or more of these types:

• overview
• getting-started
• concept
• entity
• process
• decision
• comparison
• glossary
• faq
• status
• timeline

The agent SHOULD pick the smallest stable page type that matches the content.

The agent MUST prefer one concept per page rather than oversized mixed-topic pages.

The agent SHOULD create a new page only when:

• The concept deserves an independent node
• Synthesis spans multiple docs
• Navigation clarity improves
• The existing page would otherwise become too broad or unstable
• A frontend knowledge section benefits from a separate discoverable page

The agent SHOULD update an existing page instead of creating a new one when the new content clearly belongs to an existing node.

For frontend usability, the agent SHOULD ensure that important topic areas have an overview page before deep leaf pages multiply.

Page Contract

Each wiki page SHOULD include:

1. Title
2. Short summary
3. Main synthesized content
4. Related links
5. Source provenance
6. Freshness metadata if available
7. Page type metadata suitable for frontend consumption

Each wiki page MUST begin with a short summary suitable for use as a frontend preview, card description, or search snippet.

This summary SHOULD:

• Fit within 1 to 3 short paragraphs
• Define the page topic clearly
• Avoid unresolved references
• Remain understandable to a newcomer

Recommended frontmatter shape:

---
page_type: concept
title: Example Concept
summary: What this concept is and why it matters.
locale: en
canonical_page_id: example-concept
translation_status: source
available_locales:
  - en
  - ru
sources:
  - ../docs/path/to/source-a.en.md
  - ../docs/path/to/source-b.en.md
status: active
audience: newcomer
tags:
  - architecture
  - runtime
related:
  - Another Page
  - Related Concept
last_compiled: 2026-04-15
confidence: 0.91
---

Recommended mirrored-locale frontmatter extension:

---
page_type: concept
title: Пример концепции
summary: Локализованное зеркало той же страницы.
locale: ru
canonical_page_id: example-concept
translation_of: ./example-concept.en.md
translation_status: mirrored-from-default
available_locales:
  - en
  - ru
sources:
  - ../docs/path/to/source-a.ru.md
  - ../docs/path/to/source-b.en.md
status: active
audience: newcomer
related:
  - Другая страница
last_compiled: 2026-04-15
confidence: 0.78
---

Recommended body shape:

# Example Concept

## Summary

Concise synthesis of the concept.

## Key Points

- Point
- Point

## Details

Explanation of how the concept works.

## Related

- [[Another Page]]
- [[Related Concept]]

## Sources

- `docs/path/to/source-a.md`
- `docs/path/to/source-b.md`

The exact format MAY vary, but the page MUST remain readable by both humans and agents.

Glossary Requirement

The agent SHOULD maintain a glossary for recurring project terminology, especially when the docs contain abbreviations, domain-specific terms, overloaded concepts, or terms likely to confuse newcomers.

If a term appears across multiple pages and may confuse newcomers, the agent SHOULD either:

• Define it in a glossary page, or
• Link it consistently to a canonical concept page

The agent SHOULD prefer glossary-backed term stability over repeated ad hoc re-explanations.

Epistemic Rules

Provenance

For every nontrivial synthesized claim, the agent SHOULD preserve a traceable path back to /docs.

The agent MUST be able to answer, at least approximately, which source doc or docs justify a wiki statement.

Confidence

If the repository or workflow supports confidence metadata, the agent SHOULD maintain it.

Confidence SHOULD reflect evidence strength, freshness, specificity, and contradiction pressure.

Confidence MUST NOT be presented as ground truth. It is an internal epistemic signal. Low confidence should be interpreted both page-locally and graph-locally: connected low-confidence pages indicate weak knowledge regions that should be improved, merged into stronger owners, or removed.

Suggested range:

• 0.90-1.00 strongly grounded and recently confirmed
• 0.75-0.89 grounded but somewhat incomplete or partially distributed across docs
• 0.50-0.74 plausible but weakly or indirectly supported
• <0.50 weak, stale, contradictory, or underdetermined

Supersession

If newer docs replace older semantics, the agent SHOULD mark prior wiki claims or pages as superseded rather than merely deleting historical context.

The agent SHOULD preserve traceability of supersession where feasible.

Suggested metadata:

• status: superseded
• superseded_by: ...
• supersedes: ...

Contradictions

If two docs appear to conflict, the agent MUST NOT silently normalize them into a fake consensus.

The agent SHOULD:

1. Identify the contradiction
2. Prefer the stronger or newer authoritative source when justified
3. Annotate the conflict when the evidence remains unresolved
4. Downgrade confidence where appropriate

Staleness

The agent SHOULD detect stale wiki content when source docs change, disappear, or imply different semantics.

Stale content SHOULD be updated, downgraded, marked stale, or marked superseded.

Evidence Discipline

The agent MUST NOT inflate sparse hints into strong conceptual claims.

Where the docs are insufficient, the wiki SHOULD remain conservative, explicit about uncertainty, and minimal in speculative interpolation.

Sync Pipeline

The agent MUST conceptually follow this pipeline.

Phase 1: Detect

The agent identifies relevant changes in /docs, including:

• Created files
• Modified files
• Deleted files
• Moved or renamed files
• Draft to active transitions
• Active to deprecated transitions
• Metadata changes relevant to authority or scope
• Glossary or terminology changes
• Top-level information architecture changes

If repository history or file diffs are available, the agent SHOULD use them.

If history is unavailable, the agent SHOULD infer likely changes from current state and user request.

Phase 2: Interpret

For each changed source, the agent SHOULD extract:

• Major topics
• Entities
• Concepts
• Decisions
• Terminology
• Relationships
• Deprecations
• Supersession signals
• Newcomer-relevant explanatory gaps
• Pages likely affected in /wiki

The agent SHOULD determine whether the change:

• Updates an existing node
• Creates a new node
• Merges nodes
• Splits a node
• Invalidates or weakens prior claims
• Requires a new overview, glossary, comparison, or getting-started page

Phase 3: Compile

The agent updates /wiki incrementally.

Compilation MAY include:

• Creating new pages
• Updating existing pages
• Removing orphan pages
• Marking stale pages
• Marking superseded pages
• Updating source lists
• Updating backlinks
• Updating aliases
• Updating summaries
• Updating tags and related links
• Updating localized index entrypoints such as index.en.md / index.<locale>.md
• Updating metadata stores such as navigation.json, state.json, graph.json, aliases.json, or locales.json, including localized field objects inside those shared manifests
• Recording completed wiki delivery work in the project-level delivery history when repository state materially changes

The agent SHOULD prefer minimal sufficient edits over gratuitous rewrites.

Phase 4: Lint

After compile, the agent SHOULD validate the wiki for:

• Orphan pages
• Broken internal links
• Duplicate concepts
• Unresolved aliases
• Stale sources
• Contradictory claims
• Oversized pages
• Empty categories
• Low-signal pages
• Index drift
• Missing overview pages for large topic clusters
• Pages with poor summaries
• Excessive jargon density
• Undefined repeated terms
• Over-deep navigation chains
• Inconsistent category placement
• Leaf pages with no discoverable inbound path from the relevant index.<locale>.md

Repository-local guard:

./.agents/skills/wiki-sync/scripts/audit-wiki-consolidation.sh

This guard fails on missing page role metadata, provenance, related-link blocks, locale mirrors, and navigation/graph reachability. It reports short pages, low-confidence pages, and graph leaves as consolidation candidates instead of blocking useful writing by heuristic.

Phase 5: Consolidate

When requested or useful, the agent MAY run consolidation:

• Merge duplicates
• Strengthen summaries
• Compress repetitive pages
• Update confidence
• Update supersession links
• Improve index structure
• Repair graph coherence
• Normalize page taxonomy
• Strengthen onboarding flow across topic clusters

Incremental vs Full Rebuild

Incremental Sync

Default mode SHOULD be incremental.

Incremental sync is preferred when:

• A small subset of docs changed
• Structure remains stable
• Page mapping remains clear
• Frontend-facing navigation structure remains mostly valid

Full Rebuild

The agent SHOULD choose or accept full rebuild when:

• Schema changed significantly
• Wiki drift is severe
• Page taxonomy changed
• Many docs moved or disappeared
• The user explicitly requests rebuild
• The current wiki appears unreliable
• Frontend navigation quality has degraded substantially
• Overview/glossary structure has become incoherent

During full rebuild, the agent MUST still preserve historical traceability when practical through source provenance, page state metadata, graph metadata, and the project-level delivery history.

Deletion and Deprecation Handling

If a source doc is deleted, the agent MUST determine whether the affected wiki content should:

• Be deleted
• Be marked stale
• Be marked deprecated
• Be marked superseded
• Be remapped to replacement docs

If a source doc is deprecated but still informative, the agent SHOULD preserve useful context while clearly marking its status.

The agent MUST NOT leave dead provenance references without marking them as stale or removed.

If a deleted or deprecated source affects newcomer understanding, the agent SHOULD ensure that overview or glossary pages remain coherent after the change.

Link and Graph Rules

The wiki SHOULD behave as a navigable semantic graph.

The agent SHOULD maintain:

• Internal links between related pages
• Aliases or canonical naming when needed
• Compact topic clusters
• A stable entry path from the relevant index.<locale>.md to important nodes
• Discoverable progression from overview pages to leaf pages
• Related links suitable for frontend rendering

The agent SHOULD avoid:

• Isolated pages with no inbound or outbound relation
• Duplicate names for the same concept
• Excessive link spam
• Giant hub pages that collapse multiple unrelated concepts

If graph.json exists, the agent SHOULD keep it aligned with page relationships.

Naming Rules

The agent SHOULD prefer stable, explicit, concept-oriented names.

The agent SHOULD:

• Reuse existing canonical names where possible
• Resolve aliases carefully
• Avoid creating near-duplicate pages due to naming variation
• Prefer conceptual clarity over source file name mirroring
• Keep names understandable to newcomers

Examples:

• Good: Execution Pipeline
• Good: Configuration Layers
• Good: Getting Started with Runtime Architecture
• Weaker: notes-from-doc-2
• Weak: misc

If ambiguity exists, the agent SHOULD anchor naming to the dominant concept expressed in /docs.

Quality Thresholds

The agent SHOULD treat a wiki page as weak if it has one or more of these properties:

• No meaningful synthesis
• No provenance
• No relationships
• Duplicate concept overlap
• Stale unsupported claims
• Only trivial paraphrase of a single source
• Excessive size without structure
• Unresolved contradiction
• Poor newcomer-facing summary
• Unexplained jargon
• Unclear position in the navigation graph

Weak pages SHOULD be improved, merged, marked stale, converted into a different page type, or removed.

Manual Edits to /wiki

The repository MAY contain manually edited wiki pages.

If manual wiki editing exists, the agent MUST act conservatively.

Preferred policy:

• Generated pages remain generated
• Manual annotations live in explicitly marked sections
• The agent preserves marked manual sections when possible
• The agent does not overwrite clearly user-authored wiki material unless asked

Recommended markers for manual preservation:

<!-- BEGIN MANUAL -->

...

<!-- END MANUAL -->

If no such convention exists, the agent SHOULD avoid destructive rewrites unless forced by explicit request.

If the repository expects /wiki to be fully generated, the agent MAY rewrite pages freely within the generated contract.

Forced Commands Semantics

When the user or caller invokes this skill explicitly, interpret requests approximately as follows.

"sync wiki"

Run incremental detect -> interpret -> compile -> lint for affected areas.

"refresh wiki"

Run sync plus confidence, freshness, summary, and related-link updates.

"rebuild wiki"

Recreate wiki artifacts from /docs comprehensively.

"lint wiki"

Do not rewrite content unless necessary for minimal repair; report or repair graph, provenance, navigation, and structural issues depending on context.

"consolidate wiki"

Merge duplicates, compress pages, improve graph coherence, update confidence and supersession, strengthen overview pages, and reduce onboarding friction.

"repair wiki"

Fix broken links, stale references, missing index entries, alias drift, missing summaries, weak taxonomy placement, and basic provenance gaps.

"regenerate page X"

Recompile only the targeted page or node if feasible.

"rebuild onboarding"

Prioritize overview, getting-started, glossary, comparison, and faq pages for major topic clusters.

The agent SHOULD infer the smallest reasonable scope from the user request.

Automatic Trigger Heuristics

In automatic operation, the agent SHOULD trigger sync when:

• /docs/** changes materially
• A doc moves between draft and active status
• A doc becomes deprecated or superseded
• Glossary or terminology changes
• Architecture or API docs change
• A top-level docs index changes
• The user asks a question whose answer would benefit from refreshed wiki structure
• Frontend-facing navigation would likely drift unless the wiki updates

The agent SHOULD avoid unnecessary sync when changes are purely cosmetic unless the repository explicitly wants style-only changes reflected in /wiki.

Doc Parsing Heuristics

When interpreting docs, the agent SHOULD prioritize:

• Headings
• Frontmatter
• Explicit status markers
• Definitions
• Normative statements
• Interface descriptions
• Process descriptions
• Decision rationales
• Deprecation markers
• Changelog-like sections
• Cross references
• Glossary definitions
• Onboarding-oriented explanatory sections

The agent SHOULD distinguish:

• Stable definitions
• Examples
• Speculative notes
• Deprecated behavior
• Implementation detail vs conceptual contract
• Expert detail vs newcomer-relevant surface explanation

Source Mapping Heuristics

The agent SHOULD maintain a many-to-many mapping between /docs and /wiki.

One doc MAY influence multiple wiki pages. One wiki page MAY synthesize multiple docs.

The agent SHOULD maintain source-to-page awareness either explicitly or implicitly.

If metadata storage exists, the agent SHOULD store something equivalent to:

• Doc -> affected wiki pages
• Wiki page -> supporting docs
• Alias -> canonical page
• Page -> confidence/freshness state
• Page -> taxonomy role
• Page -> related pages
• Page -> newcomer relevance or audience level

Delivery-History Rules

The agent MUST NOT create or update wiki/log.<locale>.md files unless the repository explicitly reintroduces wiki-local logs.

For this repository, meaningful completed wiki work belongs in CHANGELOG.md, while open wiki work belongs in BACKLOG.md only when it remains a concrete unfinished deliverable.

A delivery-history entry SHOULD include impacted areas and concise rationale without duplicating metadata already stored in /wiki/_meta.

Failure Behavior

If sync cannot be completed fully, the agent MUST prefer partial truthful progress over pretending completion.

The agent SHOULD:

• Update what can be updated safely
• Mark uncertain areas
• Note unresolved contradictions or missing evidence
• Avoid fabricated confidence
• Preserve frontend-stable artifacts where possible
• Avoid destructive churn when evidence is insufficient

The agent MUST explicitly acknowledge when:

• Sources are missing
• Provenance is incomplete
• Rebuild scope is partial
• Manual wiki content prevented safe overwrite
• Contradictions remain unresolved
• Frontend-facing navigation remains partially degraded

Interaction Contract

When using this skill in an interactive workflow, the agent SHOULD:

• State whether it is performing incremental sync, rebuild, lint, repair, or consolidation
• Mention the main affected areas
• Surface contradictions or drift early
• Report what changed in concise operational terms
• Mention if onboarding/navigation pages were affected
• Avoid verbose process narration

The agent SHOULD not ask unnecessary clarifying questions if it can proceed safely from repository state and user request.

Safe Defaults

Unless repository conventions explicitly say otherwise, the agent MUST default to:

• /docs authoritative
• /wiki generated derivative
• Incremental sync first
• Provenance preserved
• Contradictions surfaced
• Confidence conservative
• Summaries concise
• Glossary encouraged
• Index compact
• No wiki-local mutation logs by default
• No /docs mutations
• No silent deletion of meaningful history
• No insider-only writing style for general wiki pages

Minimal Operational Checklist

On each sync, the agent SHOULD attempt to ensure:

1. Changed docs identified
2. Affected wiki pages identified
3. Pages updated or created
4. Stale or superseded pages marked
5. index.<locale>.md refreshed for the affected locales
6. Project-level delivery history updated when repository state materially changes
7. Broken links checked
8. Duplicate concepts checked
9. Provenance preserved
10. Contradictions handled honestly
11. Summaries suitable for frontend rendering
12. Large topic areas retain overview discoverability
13. Recurring terms remain defined or linked canonically

Preferred Output Style for Generated Wiki

The agent SHOULD write wiki content in a style that is:

• Compact
• Explicit
• Navigable
• Concept-first
• Low on filler
• High on structural clarity
• Readable by newcomers
• Stable under frontend rendering

The wiki SHOULD optimize for future agent and human reuse, not literary flourish.

The agent SHOULD prefer:

• Short opening summaries
• Crisp headings
• Clear distinctions
• Explicit terminology
• Stable linkable sections

The agent SHOULD avoid:

• Unexplained project slang
• Unnecessary rhetorical flourish
• Dense insider compression without definitions
• Bloated paragraphs
• Weakly justified abstraction jumps

Upgrade Path

This skill MAY evolve in maturity.

v0

• Create/update summary pages
• Maintain index and metadata

v1

• Add backlinks
• Add page taxonomy
• Add source mapping

v2

• Add confidence
• Add supersession
• Add contradiction handling
• Add staleness handling
• Add frontend summary discipline

v3

• Add typed graph artifacts
• Add alias resolution
• Add consolidation passes
• Add stronger lint and repair behavior
• Add onboarding-quality audits

The agent SHOULD use the highest maturity level supported by the repository context without forcing unnecessary complexity.

Final Rule

The agent MUST treat wiki synchronization as semantic compilation, not mere summarization.

The objective is not to duplicate /docs.

The objective is to maintain a compact, truthful, navigable, provenance-aware, cross-linked /wiki that stays aligned with /docs while also serving as a frontend-renderable onboarding and reference layer for newcomers to the project.