docs: consolidate kernel roadmap, refresh architecture + crate READMEs

[ekryski]

What this is

Docs-only. No code changes — consolidates the kernel-organization docs into one reference, brings the architecture/crate docs up to date with the current (multi-backend, subprocess-runner, convolution/-consolidated) codebase, and removes a pile of redundancy.

Kernel docs: 3 → 1 + a relocated style guide

The kernel-organization story was spread across three overlapping docs with heavy duplication (file skeleton, variants, primitives, and block-scaled patterns each appeared 2–4×). Split cleanly by purpose:

• docs/specs/KERNEL_CONSOLIDATION_PLAN.md (new, the singular roadmap) ← KERNEL_ORGANIZATION.md + CONV_CONSOLIDATION_PLAN.md + the structural parts of CONV_KERNEL_PATTERNS.md. Covers the kernels/<family>/ target layout (dropping the mlx/ + ffai/ split), the three LOC-reduction tools (shared primitives → #[kernel(variants(...))] → op×format merge), the proven convolution/ exemplar, and the family-by-family migration order.
• docs/STYLE_GUIDE.md (moved from crates/metaltile-std/, the authoring authority) ← the existing style guide + CONV_KERNEL_PATTERNS.md's authoring content. De-mlx/ffai'd, the removed #[bench] name key fixed, a shared-primitives section added. docs/developing.md now links to it.
• Deleted: KERNEL_ORGANIZATION.md, CONV_CONSOLIDATION_PLAN.md, CONV_KERNEL_PATTERNS.md, and the duplicate convolution/PATTERNS.md + PLAN.md.

Roadmap (where files go) vs authoring (how to write one kernel) are now one doc each.

ARCHITECTURE.md updated to today's codebase

• Multi-backend codegen — the CodegenBackend seam (Target = Metal/Cuda/Hip/Spirv, TargetProfile, MmaStrategy, the msl/cuda/hip/spirv generators); Metal default, CUDA/HIP/Vulkan feature-gated and validated by the GPU-vs-GPU reference corpora.
• Subprocess execution — the runner is no longer in-process; tile spawns __tile_runner and streams ProtocolMessages. Rewrote that section + the bench/test diagrams.
• metaltile-std modules (mlx/ffai/convolution/quant), the command set (clean/config, emit = build --emit, --backend), and the renamed metric path.

Crate READMEs brought current

All seven crates/*/README.md audited and fixed: codegen/runtime/facade no longer "Metal only"; metaltile-core's GpuFamily is in protocol.rs; metaltile-macros paths corrected + the dead #[kernel(bench(op=,class=,mlx=))] system replaced with #[bench]/#[test_kernel]/variants; metaltile-std rewritten as the kernel stdlib (not "benchmark metadata"); metaltile-cli gains the missing subcommands + --backend.

Also

• Moves the temporary hip_vulkan_phase* / cuda_bench_report markdown into docs/specs/.

This removes far more than it adds — +318 / −2866 lines, mostly redundancy. All internal doc links verified to resolve.

[TheTom]

Strong consolidation. I went through each doc against the current code; notes below.

What's implemented vs. aspirational, doc by doc. ARCHITECTURE.md is accurate to today's codebase: the subprocess runner is real (ProjectRunner spawns __tile_runner and parses ProtocolMessage lines, landed in #249 and refined in #260), --backend cuda|hip|vulkan routes through the feature-gated devices exactly as described, and all four referenced corpus files exist, vulkan_sdpa_multi.rs included. KERNEL_CONSOLIDATION_PLAN.md is correctly framed as a roadmap, with two spots where target state reads as achieved: the wave table marks conv/ done while §4 lists open phases for it (remaining macro_rules!, unmerged _block_scaled/_mma files), and the ~1,600 LOC figure in the Before/After table is a target, worth labeling as such. The style guide is the one doc that lags both directions, see below.

Style guide content didn't make it into the diff. docs/STYLE_GUIDE.md is a 100% similarity rename, but the body describes content changes (de-mlx/ffai, #[bench] name-key fix, new shared-primitives section). As it stands the guide still routes new kernels into mlx/ vs ffai/ (§1) and blesses the ffai_ prefix (§3), both of which the plan removes, and it teaches #[bench(name = "...")] in §2/§5/§7/§10, which the macro no longer accepts (bench.rs doc: the bench name is always the function name), so the worked examples won't compile. The plan's §3 also points to "STYLE_GUIDE §5–6" for shared-primitives authoring detail, but no doc has that section yet.

Kernel registry could use a paragraph in ARCHITECTURE.md while we're here. Registration spans three crates: metaltile-core re-exports inventory for macro-expanded submit! calls, metaltile-codegen owns KernelEntry/all_kernels() (placed next to KernelInlinePass, its only consumer), and the facade's harness/registry.rs holds the bench/test registries. The __tile_runner bin in metaltile-std exists largely to extern crate metaltile_std; so the linker keeps the inventory statics, and tile init scaffolds a per-project copy. All working, but the linker-force line is load-bearing and easy to "clean up" by accident, and the three-crate split isn't obvious from the doc. Worth capturing the why, not just the what.

Leftover dead-system refs. crates/metaltile/README.md:100,188 and crates/metaltile-macros/README.md:216 still document #[kernel(bench(...))]. Body line count is also stale (+476/-3240 now).

Two suggested additions. (1) §9.1 calls the ffai_ → mt_ rename non-breaking, but downstream consumers reference the generated Swift symbols directly, so each family migration needs a paired consumer-side PR; worth a sentence. (2) A short note on sequencing the family git mv waves around in-flight kernel branches would save everyone rebase pain.

Happy to take any of these as follow-ups if you'd rather land the bulk now.

[ekryski]

As per @0xClandestine's request, as relayed to me by @TheTom, closing in favour of moving rapid iteration to forks