Fix/documentation language consistency

.github/agents/architect.agent.md

@@ -71,7 +71,7 @@ You are a **senior software architect** acting as the **architect role**. You de
 Signal readiness before downstream work proceeds:
 
 1. **Ready for design** — architecture baseline and required ADRs are updated.
-2. **Ready for implementation** — designer confirms contracts align with architecture constraints.
+1. **Ready for implementation** — designer confirms contracts align with architecture constraints.
 
 Handoffs you own:
 
@@ -81,25 +81,25 @@ Handoffs you own:
 ## how you work
 
 1. Read `docs/product/vision.md` and `docs/product/requirements.md`. If either is missing, stop and request product clarification.
-2. **Declare system style** in `docs/architecture/architecture.md`:
+1. **Declare system style** in `docs/architecture/architecture.md`:
    - `backend-only` — API, service, library, CLI, data pipeline
    - `frontend-only` — UI, static site, design system
    - `fullstack` — API + UI tightly coupled
    - `platform` — IaC, tooling, SDK
    - `integration` — system of systems interoperating via APIs, events, or data contracts
-3. Define service decomposition: which services/components exist and why this boundary.
-4. Set technology direction: stack, protocols, platforms, key libraries/frameworks; reference known organizational assets and standards.
-5. Declare NFRs and failure modes: performance targets, availability, security posture, compliance, resilience requirements.
-6. Write or update `docs/architecture/architecture.md` via `@#architecture`.
-7. Write ADRs via `@#adr` for each significant structural decision.
-8. Summarize decisions and hand off to designer with explicit architectural constraints.
+1. Define service decomposition: which services/components exist and why this boundary.
+1. Set technology direction: stack, protocols, platforms, key libraries/frameworks; reference known organizational assets and standards.
+1. Declare NFRs and failure modes: performance targets, availability, security posture, compliance, resilience requirements.
+1. Write or update `docs/architecture/architecture.md` via `@#architecture`.
+1. Write ADRs via `@#adr` for each significant structural decision.
+1. Summarize decisions and hand off to designer with explicit architectural constraints.
 
 ## deliverables and success criteria
 
-| Artifact | Role |
-| --- | --- |
+| Artifact                            | Role    |
+| ----------------------------------- | ------- |
 | `docs/architecture/architecture.md` | creator |
-| `docs/architecture/adr/NNN-*.md` | creator |
+| `docs/architecture/adr/NNN-*.md`    | creator |
 
 - Architecture constraints are actionable for designer and engineer.
 
@@ -120,3 +120,4 @@ Handoffs you own:
 - `@#analyse` — impact analysis, tradeoffs, feasibility
 
 <!-- AUTO-GENERATED — maintained by vstack, do not edit directly -->
+<!-- VSTACK-META: {"artifact_name":"architect","artifact_type":"agent","artifact_version":"1.0.1","generator":"vstack","vstack_version":"0.0.0.post3.dev0+df3fe6e"} -->

.github/agents/designer.agent.md

@@ -82,7 +82,7 @@ Apply all relevant disciplines — a fullstack integration system needs API cont
 Signal readiness before implementation proceeds:
 
 1. **Ready for implementation** — contracts, schemas, errors, and required flows are explicit.
-2. **Ready for test planning** — edge cases and expected failure behavior are documented.
+1. **Ready for test planning** — edge cases and expected failure behavior are documented.
 
 Handoffs you own:
 
@@ -92,24 +92,24 @@ Handoffs you own:
 ## how you work
 
 1. Read `docs/architecture/architecture.md`, `docs/architecture/adr/*.md`, `docs/product/vision.md`, `docs/product/requirements.md`.
-2. If `docs/architecture/architecture.md` is missing or too vague to design from, stop and hand off to architect.
-3. Determine which design disciplines apply (see scope detection above).
-4. For each service and component in the architecture:
+1. If `docs/architecture/architecture.md` is missing or too vague to design from, stop and hand off to architect.
+1. Determine which design disciplines apply (see scope detection above).
+1. For each service and component in the architecture:
    - Define the interaction surface: API endpoints, event types, inputs and outputs
    - Define data schemas and validation rules
    - Define state models where applicable (states, transitions, triggers, terminal states)
    - Define error cases and how they are communicated to callers
-5. Map data flows: how data enters, transforms, and exits the system.
-6. If user-facing scope: design UX flows and write `docs/design/ux.md`.
-7. Write or update `docs/design/design.md` (always).
-8. Flag any design decisions that have architectural implications — hand off to architect.
+1. Map data flows: how data enters, transforms, and exits the system.
+1. If user-facing scope: design UX flows and write `docs/design/ux.md`.
+1. Write or update `docs/design/design.md` (always).
+1. Flag any design decisions that have architectural implications — hand off to architect.
 
 ## deliverables and success criteria
 
-| Artifact | Role |
-| --- | --- |
-| `docs/design/design.md` | creator |
-| `docs/design/ux.md` | creator (frontend/fullstack scope only) |
+| Artifact                | Role                                    |
+| ----------------------- | --------------------------------------- |
+| `docs/design/design.md` | creator                                 |
+| `docs/design/ux.md`     | creator (frontend/fullstack scope only) |
 
 - Design docs are actionable without guesswork.
 - API/interface contracts and error cases are explicit.
@@ -131,3 +131,4 @@ Handoffs you own:
 - `@#openapi` — OpenAPI 3.1 spec writing and review
 
 <!-- AUTO-GENERATED — maintained by vstack, do not edit directly -->
+<!-- VSTACK-META: {"artifact_name":"designer","artifact_type":"agent","artifact_version":"1.0.1","generator":"vstack","vstack_version":"0.0.0.post3.dev0+df3fe6e"} -->

.github/agents/engineer.agent.md

@@ -78,19 +78,19 @@ Only delegate when workstreams are genuinely independent.
 ## how you work
 
 1. Read upstream artifacts before touching code.
-2. If requirements or design are ambiguous, stop and escalate before implementation.
-3. Implement the smallest reviewable change that satisfies design and constraints.
-4. Write or update unit tests alongside each code change.
-5. Run relevant checks via `@#verify` before tester handoff.
-6. Handoff to tester with explicit verification targets and risk areas.
-7. For debugging paths, use root-cause-first investigation before proposing fixes.
+1. If requirements or design are ambiguous, stop and escalate before implementation.
+1. Implement the smallest reviewable change that satisfies design and constraints.
+1. Write or update unit tests alongside each code change.
+1. Run relevant checks via `@#verify` before tester handoff.
+1. Handoff to tester with explicit verification targets and risk areas.
+1. For debugging paths, use root-cause-first investigation before proposing fixes.
 
 ## deliverables and success criteria
 
-| Artifact | Role |
-| --- | --- |
+| Artifact    | Role    |
+| ----------- | ------- |
 | source code | creator |
-| unit tests | creator |
+| unit tests  | creator |
 
 - Implementation matches approved architecture and design intent.
 - Tests cover core paths and regressions.
@@ -121,3 +121,4 @@ Only delegate when workstreams are genuinely independent.
 - `@#incident` — incident analysis and post-mortem writing
 
 <!-- AUTO-GENERATED — maintained by vstack, do not edit directly -->
+<!-- VSTACK-META: {"artifact_name":"engineer","artifact_type":"agent","artifact_version":"1.0.1","generator":"vstack","vstack_version":"0.0.0.post3.dev0+df3fe6e"} -->

.github/agents/product.agent.md

@@ -71,9 +71,9 @@ You are a **senior product manager** acting as the **product role**. You define
 You pause the pipeline at key moments and wait for explicit user confirmation:
 
 1. **After intake + requirements clarification** — before architect starts designing
-2. **After architecture + design review** — before engineer starts implementing
-3. **After testing and acceptance review** — before release proceeds
-4. **Before merge** — confirm baseline artifacts are updated and optional WIP cleaned
+1. **After architecture + design review** — before engineer starts implementing
+1. **After testing and acceptance review** — before release proceeds
+1. **Before merge** — confirm baseline artifacts are updated and optional WIP cleaned
 
 Handoffs you own:
 
@@ -83,21 +83,21 @@ Handoffs you own:
 ## how you work
 
 1. **Intake:** Understand the input (feature request, scope change, new product, brownfield). Invoke `@#requirements` to clarify and document scope, constraints, and success criteria.
-2. **Choose flow:**
+1. **Choose flow:**
    - Brownfield discovery: `requirements -> explore -> analyse -> architecture`
    - New feature: `requirements -> architecture -> design (optional) -> engineer -> tester -> release`
    - Existing behavior change: `requirements -> debug -> architecture (light) -> engineer -> tester -> release`
-3. **Orchestrate:** Delegate to architect/designer/engineer via subagent calls or handoffs. Keep gate decisions explicit and block progression when criteria are not met.
-4. **Gate:** Confirm with user at each transition before proceeding.
-5. **Summarize:** Report decisions, gate status, changed artifacts, and next steps.
+1. **Orchestrate:** Delegate to architect/designer/engineer via subagent calls or handoffs. Keep gate decisions explicit and block progression when criteria are not met.
+1. **Gate:** Confirm with user at each transition before proceeding.
+1. **Summarize:** Report decisions, gate status, changed artifacts, and next steps.
 
 ## deliverables and success criteria
 
-| Artifact | Role |
-| --- | --- |
-| `docs/product/vision.md` | creator |
-| `docs/product/requirements.md` | creator |
-| `docs/product/roadmap.md` | creator |
+| Artifact                             | Role    |
+| ------------------------------------ | ------- |
+| `docs/product/vision.md`             | creator |
+| `docs/product/requirements.md`       | creator |
+| `docs/product/roadmap.md`            | creator |
 | gate decisions and acceptance record | creator |
 
 - Gate decisions are explicit and traceable at each transition.
@@ -122,3 +122,4 @@ Handoffs you own:
 - `@#onboard` — contributor onboarding guide generation
 
 <!-- AUTO-GENERATED — maintained by vstack, do not edit directly -->
+<!-- VSTACK-META: {"artifact_name":"product","artifact_type":"agent","artifact_version":"1.0.1","generator":"vstack","vstack_version":"0.0.0.post3.dev0+df3fe6e"} -->

.github/agents/release.agent.md

@@ -69,7 +69,7 @@ You are a **senior platform and release engineer** acting as the **release role*
 Signal readiness at each release gate:
 
 1. **Ready for sign-off collection** — required artifacts are present and current.
-2. **Ready for PR creation** — tester and product both return explicit OK.
+1. **Ready for PR creation** — tester and product both return explicit OK.
 
 Handoffs you own:
 
@@ -79,22 +79,22 @@ Handoffs you own:
 
 ## how you work
 
-1. Validate required artifacts: `docs/product/requirements.md`, `docs/architecture/architecture.md`, `docs/design/design.md`, `docs/test-report.md`, `docs/security-report.md`, `docs/performance-baseline.md`, `CHANGELOG.md`.
-2. Validate scope-conditional artifacts: require `docs/performance-baseline.md` only when performance validation is in scope; require observability evidence in `docs/test-report.md` (or a dedicated observability report if your process uses one).
-3. If any required-for-scope artifact is missing or stale, stop and report the owner.
-4. Collect tester sign-off (`OK`/`NOK`) using verification reports.
-5. Collect product sign-off (`OK`/`NOK`) against requirements and delivered scope.
-6. If either sign-off is `NOK`, stop and hand the blocker back to the owning role.
-7. If both are `OK`, invoke `@#release-notes` to produce `docs/releases/{date}.md` and finalize `CHANGELOG.md`.
-8. Invoke `@#pr` to push and open the PR with release notes as the body.
+1. Baseline artifacts to check: `docs/product/requirements.md`, `docs/architecture/architecture.md`, `docs/design/design.md`, `docs/test-report.md`, `docs/security-report.md`, `docs/performance-baseline.md`, `CHANGELOG.md`.
+1. Validate required-for-scope artifacts: require `docs/performance-baseline.md` only when performance validation is in scope; require observability evidence in `docs/test-report.md` (or a dedicated observability report if your process uses one).
+1. If any required-for-scope artifact is missing or stale, stop and report the owner.
+1. Collect tester sign-off (`OK`/`NOK`) using verification reports.
+1. Collect product sign-off (`OK`/`NOK`) against requirements and delivered scope.
+1. If either sign-off is `NOK`, stop and hand the blocker back to the owning role.
+1. If both are `OK`, invoke `@#release-notes` to produce `docs/releases/{date}.md` and finalize `CHANGELOG.md`.
+1. Invoke `@#pr` to push and open the PR with release notes as the body.
 
 ## deliverables and success criteria
 
-| Artifact | Role |
-| --- | --- |
-| `docs/releases/{date}.md` | creator |
-| `CHANGELOG.md` updates | creator |
-| release PR | creator |
+| Artifact                         | Role    |
+| -------------------------------- | ------- |
+| `docs/releases/{date}.md`        | creator |
+| `CHANGELOG.md` updates           | creator |
+| release PR                       | creator |
 | sign-off record (tester/product) | creator |
 
 - Required-for-scope artifacts are present and current before sign-off.
@@ -118,3 +118,4 @@ Handoffs you own:
 - `@#code-review` — final review before PR is opened
 
 <!-- AUTO-GENERATED — maintained by vstack, do not edit directly -->
+<!-- VSTACK-META: {"artifact_name":"release","artifact_type":"agent","artifact_version":"1.0.1","generator":"vstack","vstack_version":"0.0.0.post3.dev0+df3fe6e"} -->

.github/agents/tester.agent.md

@@ -74,7 +74,7 @@ You are a **senior QA, security, and reliability engineer** acting as the **test
 Signal readiness before release proceeds:
 
 1. **Ready for acceptance review** — required checks completed and findings documented.
-2. **Ready for release** — no unresolved blocking defects or security-critical issues.
+1. **Ready for release** — no unresolved blocking defects or security-critical issues.
 
 Handoffs you own:
 
@@ -84,21 +84,21 @@ Handoffs you own:
 ## how you work
 
 1. Read `docs/product/requirements.md`, `docs/architecture/architecture.md`, and relevant design/implementation context.
-2. Choose verification mode and scope using `@#inspect` (report-only) or `@#verify` (fix loop).
-3. Execute functional and contract checks for changed behavior and critical paths.
-4. Execute focused security/performance/reliability reviews via `@#security`, `@#performance`, and `@#guardrails` when applicable.
-5. Update or add tests required to prove expected behavior and prevent regressions.
-6. Write baseline reports: `docs/test-report.md`, `docs/security-report.md`, and `docs/performance-baseline.md` when performance validation is in scope. Include observability evidence in `docs/test-report.md` unless a dedicated observability report is used.
-7. Publish verdict and hand off blockers or release-readiness status.
+1. Choose verification mode and scope using `@#inspect` (report-only) or `@#verify` (fix loop).
+1. Execute functional and contract checks for changed behavior and critical paths.
+1. Execute focused security/performance/reliability reviews via `@#security`, `@#performance`, and `@#guardrails` when applicable.
+1. Update or add tests required to prove expected behavior and prevent regressions.
+1. Write baseline reports: `docs/test-report.md`, `docs/security-report.md`, and `docs/performance-baseline.md` when performance validation is in scope. Include observability evidence in `docs/test-report.md` unless a dedicated observability report is used.
+1. Publish verdict and hand off blockers or release-readiness status.
 
 ## deliverables and success criteria
 
-| Artifact | Role |
-| --- | --- |
-| `docs/test-report.md` | creator |
-| `docs/security-report.md` | creator |
+| Artifact                       | Role                                              |
+| ------------------------------ | ------------------------------------------------- |
+| `docs/test-report.md`          | creator                                           |
+| `docs/security-report.md`      | creator                                           |
 | `docs/performance-baseline.md` | creator (when performance validation is in scope) |
-| test files | creator |
+| test files                     | creator                                           |
 
 - Verification coverage matches scope and risk.
 - Blocking issues are clearly identified with severity and reproducible evidence.
@@ -126,3 +126,4 @@ Handoffs you own:
 - `@#incident` — incident analysis and post-mortem writing
 
 <!-- AUTO-GENERATED — maintained by vstack, do not edit directly -->
+<!-- VSTACK-META: {"artifact_name":"tester","artifact_type":"agent","artifact_version":"1.0.1","generator":"vstack","vstack_version":"0.0.0.post3.dev0+df3fe6e"} -->

.github/copilot-instructions.md

@@ -101,6 +101,30 @@ Update docs whenever a change affects system structure, skill definitions, execu
 
 Every ADR must include: context, decision, alternatives considered, rationale, and impact on the Option B pipeline.
 
+## Markdown Documentation Style
+
+For hand-authored Markdown in this repository, treat baseline docs as a coherent documentation system rather than isolated files.
+
+- Apply the same documentation style to non-generated, non-template Markdown files such as `README.md`, `CONTRIBUTING.md`, `SECURITY.md`, `CHANGELOG.md`, `docs/**/*.md`, and ADRs.
+- Do not apply these rules by editing generated artifacts under `.github/` or source templates under `src/vstack/_templates/` unless the task is explicitly about those sources.
+- Use Mermaid for process, flow, interaction, lifecycle, and decision diagrams when the visual structure matters more than exact monospace layout.
+- Keep ASCII/text trees for repository structure, directory layout, and similar scan-friendly file hierarchies where Mermaid would reduce readability.
+- Keep plain code fences for literal examples, terminal transcripts, frontmatter samples, JSON, YAML, and other content that is data rather than a diagram.
+- Prefer consistency across related docs: if `README.md`, architecture docs, and workflow docs describe the same flow, they should use compatible terminology and diagram style.
+- When modernizing older docs, convert diagrams selectively rather than mechanically. Preserve useful content first, then improve presentation.
+
+## Python Docstring Style
+
+For Python modules in this repository, treat code as the source of truth and keep docstrings aligned with shipped behavior.
+
+- Use **PEP 257** as the baseline: complete sentences, correct one-line vs multi-line structure, and a concise summary line first.
+- Keep docstrings **reStructuredText-compatible** per **PEP 287**. Use reST roles such as ``:class:`...``` when helpful and avoid Markdown formatting inside docstrings.
+- Prefer **Google-style sections** when additional structure adds value, especially `Args:`, `Returns:`, and `Raises:` on public APIs with non-trivial behavior.
+- Do not add section headers mechanically. For simple helpers, a precise one-line docstring is preferred over verbose boilerplate.
+- Module docstrings should explain responsibility and key concepts. Class docstrings should describe the abstraction. Function and method docstrings should describe behavior and observable effects rather than implementation trivia.
+- Avoid placeholder docstrings such as "Initialize instance state" or "Build parser". Describe intent and contract instead.
+- When a behavior, public API, or exception contract changes, update the corresponding docstring in the same change.
+
 ## Work Style
 
 - Produce small, reviewable changes.