feat: Enhance documentation and workflow clarity; add CI configuration for automated checks

docs/OPEN_QUESTIONS.md

@@ -13,11 +13,13 @@ Each question is tagged with the phase it blocks or most affects: [P0], [P1], [P
 - 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.
-- Materials are also extensible entities. The core material record (name, quantity, unit) can carry domain-specific extension payloads using the same mechanism as project extensions. Community-defined material type schemas (e.g. yarn, filament, PCB component) can be layered on without modifying the core model.
+- Materials are project-scoped entries with a fixed core shape: display name, structured quantity, unit, and optional note. Material entries are embedded within a project revision rather than modeled as independent top-level entities in Phase 1. Each material entry can carry the same extension payload mechanism as project extensions. Community-defined material type schemas (e.g. yarn, filament, PCB component) can be layered on without modifying the core model.
+- Required tools are project-scoped entries with a lightweight core shape: display name and optional note. Tools are embedded within a project revision rather than modeled as independent top-level entities in Phase 1. Each tool entry can carry optional metadata such as skill level, safety notes, and alternatives. A shared tool taxonomy remains a future option, not a Phase 1 requirement.
 - **Database: PostgreSQL is the primary persistence target.** JSONB, native full-text search, transactional consistency under concurrent federation fan-in, and broad managed hosting support make it the clear long-term fit. The persistence layer is behind a repository abstraction (trait-based interfaces), which keeps business logic independent of the database driver and leaves SQLite viable as a future lightweight self-hosting option without requiring changes to domain logic. See [ADR TBD: Persistence Layer Architecture].
 - **Baseline content prohibitions (hardcoded, not operator-configurable):** CSAM, doxxing, and non-consensual intimate imagery (NCII) are prohibited on any FeDIY instance regardless of operator policy. The guiding principle is **consent**: minors cannot consent to sexual content; individuals have not consented to having their private identifying information published; subjects of intimate imagery have not consented to its distribution. Enforcement is in-code as far as technically feasible (hash-matching for CSAM and NCII; upload-time pattern detection and mandatory human-review tooling for doxxing). Weapons, violence, and similar dual-use content are **not** hardcoded prohibitions — legitimate DIY projects (fireworks, blacksmithing, knife-making) are indistinguishable at the software level and are handled by operator content policy and community moderation.
 - **Personal data register (Q38):** Full register in ARCHITECTURE.md. Required registration fields: email, password hash, handle, display name, minimum-age-verified boolean (raw DOB discarded after age check). IP addresses never stored — ephemeral only. Optional profile fields (bio, avatar, header image, location, preferred crafts, pronouns, external links, locale, display preferences) all under contract. Analytics must be truly aggregate/anonymised — per-user event streams require consent. Handles are changeable with a redirect from old to new URL.
 - **Project revision model (Q1):** Use immutable numbered revisions plus mutable drafts. Projects may reference other projects as reusable sub-processes or prerequisites, but recursive content is represented as a graph of project references rather than inline embedding of entire project bodies. Each publish action snapshots materials, tools, steps, media references, canonical links, extension payloads, and any project references as-of publish time. Full history is visible in the API and UI, with the latest published revision as the default view.
+- **Federated material catalogs and shared vocabularies (Q2e):** Deferred to Phase 2/P3. Federated material type catalogs, tool registries, and other shared domain vocabularies as ActivityPub objects are a future option enabled by the current extension model, not a Phase 1 requirement. The typed JSON extension block mechanism (Q2c/Q2d) is designed to accommodate future federated catalog entries without requiring core schema changes. Authorization, governance, and RTBF semantics for federated community-curated catalogs will be explored in Phase 2+.
 
 ## Upfront Clarification Plan (P0 -> Early P1)
 
@@ -55,49 +57,35 @@ The goal is to remove ambiguity before implementation while keeping scope realis
 
 Decision: immutable numbered revisions plus mutable drafts. Projects may reference other projects as reusable sub-processes or prerequisites, but recursive content is represented as a graph of project references rather than inline embedding of entire project bodies. Publishing freezes a revision snapshot; later edits create a new draft and then a new numbered revision. Full history is visible in API and UI, with the latest published revision as the default view.
 
-**Q2 [P1]** How are materials modelled?
+**Q2 [P1]** ~~How are materials modelled?~~ **RESOLVED — see Resolved Decisions and ARCHITECTURE.md Project Domain Baseline.**
 
-- 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?
-- Are materials solely inline entries within a project, or are they also independent top-level entities that can be referenced by multiple projects?
-- Does the core material record have a fixed set of fields (name, quantity, unit, optional note) with extension payloads carrying domain-specific attributes? Or is the entire material record opaque beyond a display name?
-- How are domain-specific material extensions (yarn weight/fibre/colourway, filament diameter/material/temperature profile, wood species/grade/finish, electronics component value/tolerance/package) represented? Same extension payload shape as project extensions, or a separate material-type schema?
-- At what phase should structured quantity/unit data be required? A unit normalisation scheme (SI base + common craft units) would enable cross-instance filtering and quantity scaling; is that P1 or later?
+Decision: project-scoped material entries with a fixed core shape: display name, structured quantity, unit, and optional note. Material entries are embedded within a project revision rather than modeled as independent top-level entities in Phase 1. Each material entry can carry the same extension payload mechanism as project extensions. Community-defined material type schemas can be layered on without modifying the core model.
 
 **Q2d [P1/P2]** What is the extension model for domain-specific material data?
 
-- Does a material entry carry the same extension payload mechanism as a project (namespaced typed block, discoverable schema)?
-- Who can define a material type schema — instance operators only, or any community contributor who publishes a schema at a well-known URL?
-- Should FeDIY ship a small set of reference material type schemas (yarn, 3D filament, electronic component) as non-mandatory examples to establish the pattern?
-- How does a client know which material type extension(s) a given entry carries, and how does it fall back gracefully when it does not support the type?
-- What is the relationship between project-level extensions and material-level extensions? Can a domain extension define both a project schema and a material schema that are versioned together?
+~~Does a material entry carry the same extension payload mechanism as a project (namespaced typed block, discoverable schema)?~~ ~~Who can define a material type schema — instance operators only, or any community contributor who publishes a schema at a well-known URL?~~ ~~Should FeDIY ship a small set of reference material type schemas (yarn, 3D filament, electronic component) as non-mandatory examples to establish the pattern?~~ ~~How does a client know which material type extension(s) a given entry carries, and how does it fall back gracefully when it does not support the type?~~ ~~What is the relationship between project-level extensions and material-level extensions? Can a domain extension define both a project schema and a material schema that are versioned together?~~
 
-**Q2e [P2/P3]** What would a federated material catalog look like?
+Decision: yes - material entries use the same typed JSON extension block model as projects. Each material extension block has a namespace, type identifier, version, and payload; clients discover them from explicit material-entry metadata and preserve unknown optional blocks opaquely. Material type schemas may be published by instance operators or the community, and a shared material taxonomy remains a future option. A domain extension may define both a project schema and a material schema, versioned separately but named consistently.
 
-- Could shared material types (e.g. a yarn colourway catalog, a filament brand/profile registry) be published as ActivityPub objects and federated between instances?
-- What ActivityPub object type would a material catalog entry use? A custom `fediy:MaterialType` in a FeDIY JSON-LD context, or an existing vocabulary term?
-- Who is authoritative for a shared catalog entry — the originating instance, a designated community instance, or a multi-instance governance process?
-- How does a material catalog entry interact with the right to erasure / RTBF? If a community-curated entry (not personal data) is federated, different deletion semantics apply than for user personal data.
-- Is a federated catalog in scope before federation is live (Phase 2), or does it only make sense alongside AP federation?
+**Q2e [P2/P3]** What would a federated material catalog look like? **RESOLVED — see Resolved Decisions above.**
 
 **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)?
+~~Free-text tools list only, or a normalized/tool taxonomy strategy?~~ ~~Should tools support optional metadata (skill level, safety notes, alternatives)?~~
+
+Decision: project-scoped tool entries with a lightweight core shape: display name and optional note. Tools are embedded within a project revision rather than modeled as independent top-level entities in Phase 1. Each tool entry can carry optional metadata such as skill level, safety notes, and alternatives. A shared tool taxonomy remains a future option, not a Phase 1 requirement.
 
 **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?
+~~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?~~
+
+Decision: multiple typed project-scoped links. A project can carry several canonical links such as homepage, source repository, build instructions, video walkthrough, and reference material. Links are project-scoped by default so they remain stable across revisions; a version-scoped link is allowed when a specific published revision needs its own source or artifact reference. Validation requires an allowed URL scheme, scheme-specific safety checks, and rejection of dangerous or nonsensical schemes.
 
 **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?
+~~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?~~
+
+Decision: typed JSON extension blocks attached to a project revision. Each block has a stable namespace, a type identifier, a version, and a payload. Namespaces are collision-resistant (for example reverse-DNS or URL-based identifiers). API and UI clients discover extensions via explicit metadata on the project revision. Known extensions are validated against their schema; unknown optional extensions are preserved opaquely and round-trip through the API; unknown required extensions may be rejected until the instance supports them.
 
 **Q3 [P1]** What is the tag and category strategy?