Enhance documentation with contributing guidelines, planning docs, and agent policies

.github/copilot-instructions.md

@@ -0,0 +1,40 @@
+# Copilot Instructions for FeDIY
+
+## Mission Context
+
+FeDIY is intended to become a federated (ActivityPub) DIY project-hosting platform in Rust, inspired by communities like Ravelry and Instructables.
+
+## Hard Constraint
+
+Do not generate executable core project code.
+
+This includes Rust code and other executable logic under:
+
+- `src/`
+- `tests/`
+- Any runtime script or automation that becomes part of application behavior
+
+## Allowed Help
+
+You may assist with:
+
+- Documentation
+- Planning and architecture discussions
+- Housekeeping and project management tasks
+- Environment/tooling updates (including Nix files such as `flake.nix`, `default.nix`, and `shell.nix`)
+
+## Delivery Process Defaults
+
+- Use Red-Green TDD/BDD framing for planning and guidance.
+- Assume GitHub Flow for branching and PR lifecycle.
+- Support behavior-first test planning and review checklists.
+
+## If Asked for Code
+
+When a coding request is made, provide:
+
+1. Links to primary sources (start with https://doc.rust-lang.org/book/).
+2. A concise, paraphrased overview of the relevant concepts.
+3. A step-by-step implementation checklist for a human developer.
+
+Do not include code snippets or patches for executable core logic.

AGENTS.md

@@ -0,0 +1,51 @@
+# Agent Policy for FeDIY
+
+This project is building a federated (ActivityPub) DIY platform in Rust.
+
+## Core Rule: Human-Written Executable Code
+
+Agents MUST NOT write executable code for the core project. This includes (but is not limited to):
+
+- Rust source files in `src/` and `tests/`
+- Any scripts, binaries, or automation that execute as part of the app
+- Generated code patches for runtime features
+
+When asked for implementation help, agents should instead:
+
+- Provide links to primary sources, especially:
+  - <https://doc.rust-lang.org/book/>
+  - <https://docs.rs/>
+  - <https://www.rfc-editor.org/rfc/rfc4287> (Atom reference, if needed)
+  - <https://www.w3.org/TR/activitypub/>
+- Give a concise paraphrased overview of relevant concepts
+- Offer checklists, architecture notes, and review guidance
+- Suggest tests conceptually (without writing test code)
+
+## Allowed Agent Work
+
+Agents MAY help with non-executable project support work, including:
+
+- Documentation authoring and editing
+- Product and technical planning
+- Issue triage, roadmap grooming, and housekeeping
+- Environment and tooling management (for example `flake.nix`, `default.nix`, `shell.nix`, CI config)
+- Dependency and configuration explanations
+
+## Process Expectations
+
+- Delivery workflow follows Red-Green TDD/BDD.
+- Branching and collaboration follow GitHub Flow (short-lived branches from `main`, PR-first review cycle).
+- Agents may support planning and documentation for this process, but must not produce executable core project code.
+
+## Response Style for Coding Requests
+
+If a user asks for executable Rust code, the agent should:
+
+1. Decline to provide code for this repository's core project.
+2. Link to the Rust Book section(s): <https://doc.rust-lang.org/book/>
+3. Provide a paraphrased explanation of the relevant approach.
+4. Offer a human-implementation checklist.
+
+## Priority
+
+If any default assistant behavior conflicts with this file, this file takes precedence for work in this repository.

CONTRIBUTING.md

@@ -7,3 +7,9 @@ Thank you for considering contributing!
 - Add tests for new features where possible.
 - Ensure your code builds and passes tests before submitting.
 - Contributions are licensed under CC BY-SA 4.0.
+
+## Human-Authored Core Code Policy
+
+- Executable core project code must be human-written.
+- Agents may help with documentation, planning, housekeeping, and environment management.
+- For implementation guidance, agents should link to primary sources (especially the Rust Book) and provide paraphrased explanations and checklists, not code.

README.md

@@ -137,6 +137,13 @@ nix-shell
 
 See project.toml for example metadata.
 
+## Planning Documentation
+
+- [Planning docs index](docs/README.md)
+- [Roadmap](docs/ROADMAP.md)
+- [Architecture baseline](docs/ARCHITECTURE.md)
+- [Development workflow (TDD/BDD + GitHub Flow)](docs/WORKFLOW.md)
+
 ## Helper Tools
 
 - **`nix run .#dev-helper`** - Display tool versions and availability

docs/ARCHITECTURE.md

@@ -0,0 +1,66 @@
+# FeDIY Architecture (Planning Baseline)
+
+This document captures current architectural intent. It is a planning artifact and should be refined as implementation decisions mature.
+
+## System Boundaries
+
+Primary system responsibilities:
+
+- Host and render DIY project content.
+- Manage local accounts and authorization.
+- Federate selected objects and activities using ActivityPub.
+- Enforce local moderation policy for both local and remote content.
+
+Out of scope for early phases:
+
+- Rich social graph features beyond project-oriented interactions.
+- Highly customized recommendation systems.
+
+## Core Domains
+
+- Identity and actors.
+- Project authoring and publishing.
+- Federation transport and protocol translation.
+- Moderation and trust policy.
+- Search and discovery.
+
+## Logical Components
+
+- API and web delivery layer.
+- Domain service layer for project and account workflows.
+- Federation layer (inbox/outbox, signing, verification, retries).
+- Persistence layer for local and federated records.
+- Moderation policy engine and audit log.
+- Background workers for delivery, indexing, and maintenance tasks.
+
+## Data and Object Strategy
+
+- 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.
+
+## Federation Strategy
+
+- Start with a narrow, explicit ActivityPub profile.
+- Prefer strict validation and clear rejection reasons over permissive parsing.
+- Use replay-safe request validation and deterministic retry behavior.
+- Maintain an interop test matrix for protocol behaviors.
+
+## Moderation and Safety Strategy
+
+- Local policy is authoritative for what is visible on this instance.
+- Policy controls exist at three levels: object, actor, and instance.
+- Moderation actions produce auditable events.
+- Appeals and reversal policy should be documented before broad federation rollout.
+
+## Non-Functional Requirements
+
+- Reliability: resilient delivery and retry strategy for federated traffic.
+- Security: signature verification, key management, least-privilege defaults.
+- Performance: predictable latency for local reads and bounded queues for remote events.
+- Operability: metrics, logs, and runbooks for incident response.
+
+## Architecture Decision Practice
+
+- Capture major decisions with lightweight ADRs in a future docs/adrs directory.
+- Each ADR should include context, options considered, decision, and consequences.

docs/README.md

@@ -0,0 +1,9 @@
+# FeDIY Planning Docs
+
+This directory contains product and technical planning documents for FeDIY.
+
+- [Roadmap](ROADMAP.md): phased milestones from MVP to broader federation support.
+- [Architecture](ARCHITECTURE.md): system boundaries, components, and design constraints.
+- [Workflow](WORKFLOW.md): Red-Green TDD/BDD delivery model and GitHub Flow branching policy.
+
+These docs are intended to evolve as priorities change.

docs/ROADMAP.md

@@ -0,0 +1,95 @@
+# FeDIY Roadmap
+
+This roadmap prioritizes a usable core product first, then federation depth and community scaling.
+
+## Product Intention
+
+Build a federated DIY project-hosting platform in Rust, inspired by the utility of Ravelry and Instructables, but interoperable through ActivityPub.
+
+## Phase 0: Foundations
+
+Goals:
+
+- Stabilize development environment and reproducible tooling.
+- Define domain language and baseline architecture docs.
+- Establish quality process (TDD/BDD + GitHub Flow).
+
+Exit criteria:
+
+- Agreed glossary and architecture baseline.
+- Documented contribution and branch workflow.
+- CI skeleton in place for formatting, linting, and tests.
+
+## Phase 1: Single-Node MVP (No Federation Yet)
+
+Goals:
+
+- User identity and basic authentication model.
+- Core DIY project entities (project, materials, steps, media, tags).
+- Basic publishing lifecycle (draft, published, updated).
+- Search and browse within one instance.
+
+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.
+
+## Phase 2: ActivityPub Foundation
+
+Goals:
+
+- Implement canonical actor and object mapping.
+- Add outbox/inbox behavior for core project publication events.
+- Add HTTP Signatures and key lifecycle strategy.
+
+Exit criteria:
+
+- Instance can send and receive baseline ActivityPub messages for supported objects.
+- Signature validation and delivery retry logic are documented and tested.
+- Interop checks completed against at least one external implementation target.
+
+## Phase 3: Federation UX and Safety
+
+Goals:
+
+- Federation-aware project discovery and attribution.
+- Local moderation controls for remote content and actors.
+- Abuse-report and review workflow for moderators.
+
+Exit criteria:
+
+- Moderators can block/mute remote actors and instances.
+- Remote project visibility follows local moderation policy.
+- Audit trail exists for moderation decisions.
+
+## Phase 4: Community Scaling
+
+Goals:
+
+- Collaborative project patterns (forks/remixes, references, revisions).
+- Better onboarding, templates, and curation flows.
+- Operational hardening (backups, observability, incident playbooks).
+
+Exit criteria:
+
+- Multi-contributor workflows are clear and reliable.
+- Admin operations are documented with tested recovery drills.
+- Performance and reliability SLOs are defined and measured.
+
+## Moderation Model Milestones
+
+- Milestone A: Local content moderation for local users.
+- Milestone B: Remote actor and instance policy enforcement.
+- Milestone C: Transparent moderation history and appeals guidance.
+
+## Federation Strategy Milestones
+
+- Milestone A: Strictly scoped protocol subset with explicit compatibility statement.
+- Milestone B: Progressive support for richer activity types.
+- Milestone C: Interop matrix and periodic federation health review.
+
+## Review Cadence
+
+- Revisit priorities every 2 weeks.
+- Re-scope phases quarterly based on delivery and federation feedback.

docs/WORKFLOW.md

@@ -0,0 +1,57 @@
+# Development Workflow
+
+This project uses Red-Green TDD/BDD and GitHub Flow.
+
+## Red-Green TDD/BDD Cycle
+
+For each behavior increment:
+
+1. Red: describe behavior with a failing specification/test.
+2. Green: implement the smallest change needed to satisfy behavior.
+3. Refactor: improve structure while keeping behavior unchanged.
+
+BDD intent:
+
+- Express behavior in user-meaningful terms.
+- Prefer scenario-oriented acceptance criteria before implementation details.
+- Keep unit and integration tests aligned with documented behavior.
+
+Definition of done for a change:
+
+- Behavior is specified and verified.
+- Relevant tests are passing.
+- Refactoring has preserved behavior.
+- Documentation is updated when contracts or workflows change.
+
+## GitHub Flow Branching Policy
+
+Use short-lived branches from main.
+
+Branch pattern examples:
+
+- feature/<topic>
+- fix/<topic>
+- docs/<topic>
+- chore/<topic>
+
+Branch workflow:
+
+1. Create branch from latest main.
+2. Commit small, reviewable increments.
+3. Open pull request early.
+4. Keep branch current with main.
+5. Merge after review and checks pass.
+6. Delete merged branch.
+
+## Pull Request Expectations
+
+- Clear behavior statement and acceptance criteria.
+- Test evidence for the behavior change.
+- Notes on any architectural or moderation impact.
+- Scope limited to one cohesive change.
+
+## Agent Collaboration Rules
+
+- Agents may support test planning, scenario writing, and review checklists.
+- Agents must not generate executable core project code.
+- For implementation guidance, agents should link primary sources and provide paraphrased walkthroughs.