epic: reframe public-facing story around the orchestrator model

[tomas-samek]

Goal

Reframe tiko-di's public-facing story so the orchestrator + event-model identity is what humans and agents absorb first. The current framing organizes everything as a Spring Boot feature comparison, which primes a "Spring minus features" reading and has led LLM agents to fail simple tasks by searching for tiko equivalents of Spring annotations instead of using the orchestrator model.

Target audience is the greenfield "start a new service" path, not migration. A migration audience would re-introduce the 1:1 Spring frame this reframing exists to remove.

Guiding principles

These gate every sub-issue.

1. Lead with what tiko IS. Spring may appear later as illustration, never as the organizing axis.
2. Three buckets. Every capability is one of:
   • Core (ours): DI, scopes, event bus, compile-time validation.
   • Plug in (orchestrated): DataSource / HikariCP, jOOQ, Flyway, Caffeine, template engines, HTTP, security libs, arbitrary SDK clients.
   • Open design questions: deliberately small — extensions to the existing event model only (async generalization, scheduling-as-tick-event, retry-as-event-loop). Avro / Schema Registry, Kotlin interop, full observability stack are tracked separately and not in this bucket — see "Out of scope".
3. Cookbook, not wrapper. tiko owns the seam (@Produces), never the surface (a library's full API). Module status is reserved for capabilities that add tiko-native primitives — e.g. tiko-kafka earns module status because it adds @KafkaSource / @KafkaSink topology validation, not because it wraps the Kafka client.
4. Banned vocabulary. "gap", "missing", "not yet supported", "limitation", "tiko's equivalent of". Replace with "plug in", "direct access", "always current", "you provide", "we deliberately don't wrap".
5. One-line pitch, used verbatim. Working draft: "Tiko orchestrates, it doesn't bundle — direct access, compile-time safe, nothing wrapped." Locked in docs: lock orchestrator vocabulary and one-line pitch #263. The same sentence appears in README (docs: rewrite README around the three-bucket orchestrator model #267), skill (docs(skill): build the tiko-build scaffolding skill #264, docs(skill): package the tiko-build skill for agent discovery #266), and archetype-generated agent-config files — agents propagate it most reliably when it never paraphrases between artifacts.
6. Show, don't tell. A working demonstration of the orchestrator model frames it more strongly than any prose claim — the skill (docs(skill): build the tiko-build scaffolding skill #264) and reference app (examples: reference orchestrator-model app for the skill to cite #265) do the heavy lifting; README (docs: rewrite README around the three-bucket orchestrator model #267) points at them.

Sub-issues

Execution order — same as listed:

• docs: lock orchestrator vocabulary and one-line pitch #263 — Lock orchestrator vocabulary and one-line pitch
• docs(skill): build the tiko-build scaffolding skill #264 — Build the tiko-build skill (cookbook + decision tree + anti-pattern redirects)
• examples: reference orchestrator-model app for the skill to cite #265 — Reference scaffolded app the skill cites (parallel with docs(skill): build the tiko-build scaffolding skill #264)
• docs(skill): package the tiko-build skill for agent discovery #266 — Skill packaging and agent discoverability (depends on docs(skill): build the tiko-build scaffolding skill #264)
• docs: rewrite README around the three-bucket orchestrator model #267 — README rewrite around the three buckets (parallel with docs(skill): benchmark the tiko-build skill across agents and frameworks #269)
• docs: sweep banned vocabulary and delete tiko-di-gap-analysis.md #268 — closed as no-op (the gap-analysis doc never landed in the repo; remaining banned-vocab hits are legitimate technical English absorbed by docs: rewrite README around the three-bucket orchestrator model #267)
• docs(skill): benchmark the tiko-build skill across agents and frameworks #269 — Benchmark the tiko-build skill across agents and frameworks (depends on docs(skill): package the tiko-build skill for agent discovery #266)

Out of scope

• New wrapper modules over third-party libraries.
• Migration guides ("migrate your Spring app to tiko") — wrong audience at 0.1.x; would re-introduce the 1:1 frame.
• Avro / Schema Registry, Kotlin interop, full observability stack — tracked separately.