Publish standalone bilingual LinxISA docs

.github/workflows/ci.yml

@@ -58,8 +58,10 @@ jobs:
           python-version: "3.11"
       - name: Install deps
         run: python -m pip install --upgrade pip "mkdocs<2" mkdocs-material
-      - name: Build docs (MkDocs)
+      - name: Build docs (English MkDocs)
         run: mkdocs build --strict
+      - name: Build docs (Chinese MkDocs)
+        run: mkdocs build --strict -f mkdocs.zh.yml -d site/zh
 
   lint:
     runs-on: ubuntu-latest

.github/workflows/pages.yml

@@ -33,9 +33,12 @@ jobs:
         run: |
           python -m pip install --upgrade pip "mkdocs<2" mkdocs-material
 
-      - name: Build MkDocs site
+      - name: Build English docs
         run: mkdocs build --strict
 
+      - name: Build Chinese docs
+        run: mkdocs build --strict -f mkdocs.zh.yml -d site/zh
+
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v5
         with:

README.md

@@ -94,15 +94,13 @@ linx-isa/
 | Submodule | Repository | Purpose |
 |-----------|------------|---------|
 | `compiler/llvm` | [LinxISA/llvm-project](https://github.com/LinxISA/llvm-project) | LLVM-based compiler for Linx |
-| `compiler/ptoas` | [LinxISA/ptoas](https://github.com/LinxISA/ptoas) | PTO assembler and PTO-to-Linx lowering toolchain |
 | `emulator/qemu` | [LinxISA/qemu](https://github.com/LinxISA/qemu) | QEMU-based emulator |
 | `kernel/linux` | [LinxISA/linux](https://github.com/LinxISA/linux) | Linux kernel port |
 | `rtl/LinxCore` | [LinxISA/LinxCore](https://github.com/LinxISA/LinxCore) | RTL implementation |
 | `tools/pyCircuit` | [LinxISA/pyCircuit](https://github.com/LinxISA/pyCircuit) | ISA reference model |
 | `lib/glibc` | [LinxISA/glibc](https://github.com/LinxISA/glibc) | GNU C Library port |
 | `lib/musl` | [LinxISA/musl](https://github.com/LinxISA/musl) | musl libc port |
 | `workloads/pto_kernels` | [LinxISA/PTO-Kernel](https://github.com/LinxISA/PTO-Kernel) | PTO accelerator kernels |
-| `skills/linx-skills` | [LinxISA/linx-skills](https://github.com/LinxISA/linx-skills) | Canonical LinxISA Codex skills |
 
 ### Updating Submodules
 
@@ -112,7 +110,7 @@ git submodule sync --recursive
 git submodule update --init --recursive
 
 # Pull latest from upstream
-git submodule update --remote compiler/llvm compiler/ptoas emulator/qemu kernel/linux rtl/LinxCore tools/pyCircuit lib/glibc lib/musl workloads/pto_kernels skills/linx-skills
+git submodule update --remote compiler/llvm emulator/qemu kernel/linux rtl/LinxCore tools/pyCircuit lib/glibc lib/musl workloads/pto_kernels
 
 # Verify layout
 bash tools/ci/check_repo_layout.sh

docs/architecture/README.md

@@ -12,32 +12,42 @@ Architecture-facing documentation lives under `docs/architecture/`.
 - `docs/architecture/v0.56-rendering-kernel-authoring.md`
 - `docs/architecture/v0.56-rendering-pto-contract.md`
 - `docs/architecture/v0.56-rendering-command-contract.md`
-- published LinxCore mirrors:
+- published LinxCore pages:
   - `docs/architecture/linxcore/overview.md`
   - `docs/architecture/linxcore/microarchitecture.md`
   - `docs/architecture/linxcore/interfaces.md`
   - `docs/architecture/linxcore/verification-matrix.md`
   - `docs/architecture/linxcore/module-catalog.md`
   - `docs/architecture/linxcore/pipeline-stage-catalog.md`
-- canonical LinxCore authoring source:
-  - `rtl/LinxCore/docs/architecture/overview.md`
-  - `rtl/LinxCore/docs/architecture/microarchitecture.md`
-  - `rtl/LinxCore/docs/architecture/interfaces.md`
-  - `rtl/LinxCore/docs/architecture/verification-matrix.md`
-  - `rtl/LinxCore/docs/architecture/module-catalog.md`
-  - `rtl/LinxCore/docs/architecture/pipeline-stage-catalog.md`
+- LinxCore source material:
+  - `rtl/LinxCore/docs/architecture/`
 
 ## ISA manual
 
 - `docs/architecture/isa-manual/`
   - AsciiDoc ISA manual source and generated PDF.
 
+## Published bilingual manual surface
+
+The published docs site now has a broader manual hierarchy than the AsciiDoc
+manual alone:
+
+- ISA/publication pages under `docs/background/`, `docs/compiler/`,
+  and the expanded `docs/isa/` tree,
+- a Chinese edition under `docs/zh/` with path parity,
+- the existing generated `docs/isa/groups/` and `docs/isa/instructions/`
+  retained as appendix/reference rather than the primary manual home.
+
+The normative rule does not change: architecture-affecting behavior is still
+owned by the English v0.56 contract pages and the English AsciiDoc manual.
+The broader manual pages are the primary published narrative surface,
+but they must stay synchronized with those normative sources.
+
 ## Governance notes
 
 - LinxArch pages are the canonical architecture contract for bring-up and gates.
 - LinxCore contract authoring lives in `rtl/LinxCore/docs/architecture/`; the
-  superproject `docs/architecture/linxcore/` pages are generated publication
-  mirrors.
+  superproject `docs/architecture/linxcore/` pages are published copies.
 - Implementation-specific deep dives in submodules must link back to these
   contract pages.
 - Any architecture-affecting change must update LinxArch first, then implementation.

docs/architecture/isa-manual/README.md

@@ -7,6 +7,17 @@ This directory contains the live v0.56.2 ISA manual for the **Linx Instruction S
 The content is specific to Linx’s design (block-structured control flow, `BSTART/BSTOP`, ClockHands temporaries,
 template instructions like `FENTRY`, etc).
 
+The docs site also publishes a broader Markdown manual hierarchy for the standalone site. That broader hierarchy is the primary public
+navigation surface, but this English AsciiDoc manual remains the normative
+English manual source for architecture-visible behavior.
+
+Related published pages:
+
+- `docs/background/`
+- `docs/compiler/`
+- `docs/isa/`
+- `docs/zh/` (Chinese edition)
+
 ## Build
 
 From this directory:

docs/architecture/linxcore/interfaces.md

@@ -1,5 +1,4 @@
 # LinxCore External Interface Contracts
-
 ## pyCircuit-LinxCore interface contract (LC-IF-PYC-001)
 
 The pyCircuit/LinxCore integration contract is versioned and gate-enforced.

docs/architecture/linxcore/microarchitecture.md

@@ -1,12 +1,4 @@
-<!-- AUTO-GENERATED FILE. DO NOT EDIT DIRECTLY. -->
-<!-- Source: rtl/LinxCore/docs/architecture/microarchitecture.md -->
-
 # LinxCore v0.56 Microarchitecture Contract
-
-> This published page mirrors the canonical LinxCore source in
-> `rtl/LinxCore/docs/architecture/microarchitecture.md`.
-
-
 ## Baseline superscalar contract
 
 LinxCore is the canonical superscalar out-of-order core for LinxISA `v0.56`.

docs/architecture/linxcore/module-catalog.md

@@ -1,12 +1,4 @@
-<!-- AUTO-GENERATED FILE. DO NOT EDIT DIRECTLY. -->
-<!-- Source: rtl/LinxCore/docs/architecture/module-catalog.md -->
-
 # LinxCore Module Catalog
-
-> This published page mirrors the canonical LinxCore source in
-> `rtl/LinxCore/docs/architecture/module-catalog.md`.
-
-
 This chapter defines the canonical module structure for LinxCore under the live
 `v0.56` superscalar contract.
 

docs/architecture/linxcore/overview.md

@@ -1,12 +1,4 @@
-<!-- AUTO-GENERATED FILE. DO NOT EDIT DIRECTLY. -->
-<!-- Source: rtl/LinxCore/docs/architecture/overview.md -->
-
 # LinxCore v0.56 Superscalar Bring-up Overview
-
-> This published page mirrors the canonical LinxCore source in
-> `rtl/LinxCore/docs/architecture/overview.md`.
-
-
 ## Scope
 
 This document is the top-level specification overview for LinxCore under the

docs/architecture/linxcore/pipeline-stage-catalog.md

@@ -1,12 +1,4 @@
-<!-- AUTO-GENERATED FILE. DO NOT EDIT DIRECTLY. -->
-<!-- Source: rtl/LinxCore/docs/architecture/pipeline-stage-catalog.md -->
-
 # LinxCore Pipeline Stage Catalog
-
-> This published page mirrors the canonical LinxCore source in
-> `rtl/LinxCore/docs/architecture/pipeline-stage-catalog.md`.
-
-
 This chapter defines the architecturally visible LinxCore stage set and the
 module that owns each stage.
 

docs/architecture/linxcore/verification-matrix.md

@@ -1,12 +1,4 @@
-<!-- AUTO-GENERATED FILE. DO NOT EDIT DIRECTLY. -->
-<!-- Source: rtl/LinxCore/docs/architecture/verification-matrix.md -->
-
 # LinxCore v0.56 Verification Matrix
-
-> This published page mirrors the canonical LinxCore source in
-> `rtl/LinxCore/docs/architecture/verification-matrix.md`.
-
-
 This matrix ties LinxCore architecture intent to strict required gates.
 
 It is the normative mapping between:

docs/architecture/v0.56-architecture-contract.md

@@ -128,16 +128,27 @@ these kernel changes:
 - `docs/architecture/linxcore/module-catalog.md`
 - `docs/architecture/linxcore/pipeline-stage-catalog.md`
 
-LinxCore-specific authoring lives in:
+## Published Manual Mirrors
 
-- `rtl/LinxCore/docs/architecture/overview.md`
-- `rtl/LinxCore/docs/architecture/microarchitecture.md`
-- `rtl/LinxCore/docs/architecture/interfaces.md`
-- `rtl/LinxCore/docs/architecture/verification-matrix.md`
-- `rtl/LinxCore/docs/architecture/module-catalog.md`
-- `rtl/LinxCore/docs/architecture/pipeline-stage-catalog.md`
+The public documentation site now exposes a broader manual
+hierarchy alongside the normative pages above:
 
-The `docs/architecture/linxcore/` pages remain the published mirrors used by
+- `docs/background/`
+- `docs/compiler/`
+- architecture/state/type/instruction-family pages under `docs/isa/`
+- a Chinese edition of the published surface under `docs/zh/`
+- generated appendix/reference pages under `docs/isa/groups/` and
+  `docs/isa/instructions/`
+
+Those published pages must not drift semantically from the normative contract.
+If a public page and a canonical contract page disagree, the contract page must
+be updated or the public page must be corrected immediately.
+
+LinxCore source material lives in:
+
+- `rtl/LinxCore/docs/architecture/`
+
+The `docs/architecture/linxcore/` pages remain the published pages used by
 mkdocs and architecture navigation.
 
 ## Conformance Gates

docs/architecture/v0.56-hardening-policy.md

@@ -37,11 +37,11 @@ These rules come from:
 - `docs/architecture/v0.56-architecture-contract.md`
 - `docs/architecture/v0.56-workload-engine-model.md`
 - `docs/architecture/v0.56-rendering-command-contract.md`
-- `docs/architecture/linxcore/microarchitecture.md` (published mirror of
+- `docs/architecture/linxcore/microarchitecture.md` (published copy of
   `rtl/LinxCore/docs/architecture/microarchitecture.md`)
-- `docs/architecture/linxcore/module-catalog.md` (published mirror of
+- `docs/architecture/linxcore/module-catalog.md` (published copy of
   `rtl/LinxCore/docs/architecture/module-catalog.md`)
-- `docs/architecture/linxcore/pipeline-stage-catalog.md` (published mirror of
+- `docs/architecture/linxcore/pipeline-stage-catalog.md` (published copy of
   `rtl/LinxCore/docs/architecture/pipeline-stage-catalog.md`)
 - `isa/v0.56/state/rendering_profile.json`
 - `docs/architecture/isa-manual/src/chapters/08_tile_blocks.adoc`