Clarify architectural vision: TransformationSpecification as IR

[amc-corey-cox]

Summary

• Sharpens the framing in docs and README to lead with the TransformationSpecification as the core value proposition — a declarative IR for data model mappings
• Documents the two execution backends: Python ObjectTransformer (full support) and SQL/DuckDB (experimental, limited subset)
• Clarifies that output serialization formats are intentionally text-based; loading into analytical stores is a downstream concern
• Fixes "ployglot" typo, updates stale "forthcoming" references

Files changed

• docs/index.md — new Architecture section, updated features list and Details section
• README.md — updated opening framing and features list
• docs/faq.md — added multi-backend framing paragraph

Related issues

• Expand SQLCompiler to cover more of the TransformationSpecification #150 — Expand SQLCompiler to cover more of the TransformationSpecification
• Flesh out DuckDBTransformer as a full execution backend #151 — Flesh out DuckDBTransformer as a full execution backend
• Document the TransformationSpecification-as-IR architectural vision #152 — Document the TransformationSpecification-as-IR architectural vision

Test plan

• Verify mkdocs builds cleanly
• Review wording for accuracy re: current SQL backend capabilities

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Updates the project documentation to frame TransformationSpecification as LinkML-Map’s declarative intermediate representation (IR), and to describe the current execution backends (Python vs experimental SQL/DuckDB) and output/serialization scope.

Changes:

• Reframes docs/README opening to lead with TransformationSpecification as the core concept (IR).
• Adds an Architecture section describing Python execution vs experimental SQL/DuckDB compilation.
• Updates feature lists and fixes/refreshes some stale wording (e.g., “polyglot”, “forthcoming”).

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
docs/index.md	Adds Architecture section; updates features and CLI compile targets; clarifies polyglot framing and output scope.
docs/faq.md	Adds a paragraph introducing the multi-backend / IR framing.
README.md	Updates opening and feature list to reflect IR-first framing and experimental SQL backend.