Enhance documentation structure and clarify project domain; add new directories for architecture, contracts, and extensions; update roadmap and open questions with resolved decisions and clarification plans.

README.md

@@ -101,8 +101,19 @@ make flatpak-build
 ```
 Cargo.toml
 Cargo.lock
+docs/
+  adrs/                  # Architecture decision records
+  contracts/             # API and behavior contracts (planning artifacts)
+  extensions/            # Extension model planning and examples
+  OPEN_QUESTIONS.md
+  ROADMAP.md
+  ARCHITECTURE.md
+schemas/
+  project-core/          # Core project schema artifacts
+  extensions/            # Domain-specific extension schema artifacts
 src/
   └── main.rs (or lib.rs)
+tests/
 Makefile
 .envrc
 flake.nix
@@ -126,6 +137,7 @@ See project.toml for example metadata.
 - [Roadmap](docs/ROADMAP.md)
 - [Architecture baseline](docs/ARCHITECTURE.md)
 - [Development workflow (TDD/BDD + GitHub Flow)](docs/WORKFLOW.md)
+- [Open questions and clarification plan](docs/OPEN_QUESTIONS.md)
 
 ## Helper Tools
 

docs/ARCHITECTURE.md

@@ -25,6 +25,19 @@ Out of scope for early phases:
 - Moderation and trust policy.
 - Search and discovery.
 
+## Project Domain Baseline
+
+Current product definition:
+
+- A project is a defined work process.
+- Core project structure includes materials/ingredients, required tools, and ordered step-by-step instructions.
+- Steps may include embedded media hosted on this instance or linked from external sources.
+- Projects may include external canonical links (for example homepage, repository, or source publication).
+- Explicit project versioning is preferred and will be part of the domain model.
+- The project model is composable: a minimal core plus optional domain-specific extensions.
+- Domain-specific detail (for example knitting patterns/yarns, 3D print profiles/STLs, electronics BoM data) should be representable without being mandatory for all instances.
+- First-party FeDIY focuses on a stable extension mechanism rather than implementing every niche schema directly.
+
 ## Client and Front-End Strategy
 
 The server exposes a stable, documented HTTP API as its primary interface. The bundled web UI is a first-party client of that same API — it receives no privileged server-side access that a third-party client could not also use.
@@ -68,6 +81,7 @@ Bundled web UI:
 - Separate local canonical records from imported federated records.
 - Preserve source metadata for remote content and actor provenance.
 - Track object lifecycle states to support idempotent federation processing.
+- Persist project data as core fields plus extension payloads so instances can tailor domain detail without fragmenting the base model.
 
 ## Federation Strategy
 

docs/OPEN_QUESTIONS.md

@@ -4,21 +4,79 @@ A living document of unresolved design and product questions. When a question is
 
 Each question is tagged with the phase it blocks or most affects: [P0], [P1], [P2], [P3], [P4].
 
+## Resolved Decisions
+
+- A "project" is a defined work process.
+- A project includes a list of materials/ingredients, a list of required tools, and step-by-step ordered instructions.
+- Steps may include embedded media hosted on-instance or linked from external sources.
+- Projects may include one or more external canonical links (for example homepage, repository, or source publication).
+- Explicit project versioning is preferred and should be supported.
+- A project is composable: FeDIY provides a minimal core model, and instances can tailor project detail via optional domain-specific extensions.
+- FeDIY should not require first-party implementation of every domain detail up front; expert communities can define richer schemas over time.
+
+## Upfront Clarification Plan (P0 -> Early P1)
+
+The goal is to remove ambiguity before implementation while keeping scope realistic.
+
+1. Decision track A: Project revision model
+
+- Resolve Q1 first.
+- Output: one ADR defining draft/publish/supersede behavior and history visibility.
+- Success signal: API and UI contracts can assume a stable project lifecycle.
+
+1. Decision track B: Core-plus-extension contract
+
+- Resolve Q2, Q2a, Q2b, and Q2c as one coherent contract.
+- Output: one ADR for core project fields and one ADR for extension payload shape/namespacing/discovery.
+- Success signal: instances can add domain-specific detail (knitting, 3D print, electronics, etc.) without changing core semantics.
+
+1. Decision track C: Search/index policy for extensions
+
+- Resolve the extension-indexing part of Q2c with Q23.
+- Output: indexing policy doc or ADR that separates required indexed fields from opaque extension fields.
+- Success signal: predictable search behavior across instances with different extensions.
+
+1. Decision track D: API stability and evolution
+
+- Resolve Q10 and Q11 before broad client development.
+- Output: API versioning/deprecation policy with compatibility guarantees for third-party clients.
+- Success signal: extension evolution does not break existing clients unexpectedly.
+
 ---
 
 ## Domain Model
 
-**Q1 [P1]** What is the canonical structure of a "project"?
+**Q1 [P1]** What should the explicit versioning model look like?
 
-- Is it steps + materials + media, or does it also include file attachments (patterns, templates, cut files)?
-- Are steps ordered (sequential instructions) or unordered (reference material)?
-- Do projects have explicit versioning/revision history, or only an updated timestamp?
+- Immutable numbered revisions, mutable drafts, or both?
+- Does each version snapshot materials, tools, steps, media references, and extension data?
+- What is the publish workflow for a new version (draft -> published -> superseded)?
+- How should old versions be exposed in API and UI (full history vs selected milestones)?
 
 **Q2 [P1]** How are materials modelled?
 
 - Free-text only, or linked to a shared taxonomy/catalog?
 - Do quantities and units need to be structured (for search/filtering), or is prose sufficient for MVP?
 
+**Q2a [P1]** How are required tools modelled?
+
+- Free-text tools list only, or a normalized/tool taxonomy strategy?
+- Should tools support optional metadata (skill level, safety notes, alternatives)?
+
+**Q2b [P1]** How are canonical external links modelled and validated?
+
+- Single canonical link or multiple typed links (homepage, repository, video, reference)?
+- Are external links version-scoped or project-scoped?
+- What URL validation and safety checks are required?
+
+**Q2c [P1/P2]** What is the extension model for domain-specific project data?
+
+- What extension shape is supported first: typed JSON blocks, namespaced key/value fields, or plugin-defined schemas?
+- How are extensions identified and namespaced to avoid collisions across instances?
+- How do API and UI clients discover which extensions are present on a project?
+- Which extension fields are indexed for search, and which remain opaque?
+- What validation guarantees does the server provide for extension payloads?
+
 **Q3 [P1]** What is the tag and category strategy?
 
 - Folksonomy (free-form user tags), curated taxonomy, or both?

docs/ROADMAP.md

@@ -13,27 +13,33 @@ Goals:
 - Stabilize development environment and reproducible tooling.
 - Define domain language and baseline architecture docs.
 - Establish quality process (TDD/BDD + GitHub Flow).
+- Clarify the core-plus-extension project contract before implementation.
 
 Exit criteria:
 
 - Agreed glossary and architecture baseline.
 - Documented contribution and branch workflow.
 - CI skeleton in place for formatting, linting, and tests.
+- ADR for project revision lifecycle (draft/publish/supersede).
+- ADR for composable extension mechanism (shape, namespacing, discovery).
+- Initial repository layout includes dedicated locations for API contracts and extension schemas.
 
 ## Phase 1: Single-Node MVP (No Federation Yet)
 
 Goals:
 
 - User identity and basic authentication model.
-- Core DIY project entities (project, materials, steps, media, tags).
+- Core DIY project entities (project, materials, tools, steps, media, canonical links, tags).
 - Basic publishing lifecycle (draft, published, updated).
 - Search and browse within one instance.
+- Support extension payloads in project data model without requiring domain-specific first-party implementations.
 
 Exit criteria:
 
 - A user can publish and update a complete project end-to-end.
 - Project pages are discoverable and readable on one node.
 - Test coverage exists for core behavior paths.
+- At least one extension payload can be stored, validated, and rendered as non-breaking optional data.
 
 ## Phase 2: ActivityPub Foundation