Document configuration precedence and repository boundaries

[bsstahl]

This change records the bootstrap architecture decisions needed before implementation starts, so configuration and storage behavior are explicit and consistent across docs.

What changed

• Added ADR-013 defining standard .NET configuration precedence: JSON baseline, environment variable overrides, and in-memory overrides last for tests and controlled bootstrap scenarios.
• Updated ARCHITECTURE.md to align file-backed data-root configuration with the repository abstraction boundary and standard .NET configuration flow.
• Updated integration planning notes to keep configuration-precedence and data-root decisions visible in the bootstrap decision set.
• Included related continuity and instruction updates in this branch so repository guidance matches the current documentation direction.

Notes for reviewers

• This PR is documentation-only and intentionally focused on implementation-readiness decisions.
• No code behavior changes are introduced here.

[Copilot]

🟡 Changes recommended

It introduces broken cross-repo relative links and a markdownlint configuration that conflicts with existing markdown list-marker usage, likely causing avoidable documentation lint failures.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR documents bootstrap architecture decisions for TalkFolio so configuration precedence and repository/storage boundaries are explicit before implementation work begins.

Changes:

• Added ADRs clarifying repository abstractions, configurable external data roots, and .NET configuration precedence (JSON, env vars, in-memory last).
• Updated integration planning docs and README to reinforce SpeakerOps boundaries and capture an MVP implementation plan.
• Added baseline contribution + architecture docs and repository-wide authoring instruction files (including markdownlint configuration).

File summaries

File	Description
README.md	Adds MVP feature framing and updates the product positioning statement.
docs/Integration-Strategy.md	Adds SpeakerOps contract notes plus MVP planning and open questions.
docs/ADRs.md	Adds ADR-011/012/013 covering repository boundaries and configuration precedence.
CONTRIBUTING.md	Introduces contribution expectations and links to repo guidance/instructions.
ARCHITECTURE.md	Captures TalkFolio architectural boundaries, layering, and configuration direction.
.markdownlint.json	Introduces markdownlint rule configuration for repo documentation.
.github/instructions/writing-style.instructions.md	Adds writing voice/tone guidance for markdown.
.github/instructions/test-methodology.instructions.md	Adds TDD methodology guidance for future C# implementation work.
.github/instructions/markdown.instructions.md	Adds markdown style conventions intended to match markdownlint rules.
.github/instructions/git-merge.instructions.md	Adds guidance for merge/rebase workflows when coordinating Git operations.
.github/instructions/csharp.instructions.md	Adds C#/.NET 10 authoring conventions for future implementation.
.github/instructions/csharp-tests.instructions.md	Adds xUnit/NSubstitute and test naming/organization guidance.
.github/copilot-instructions.md	Adds top-level agent instructions aligned to the repo’s intended conventions.

Review details

Suppressed comments (2)

docs/Integration-Strategy.md:12

• These links point outside this repository (../../SpeakerOps/...) and will be broken when viewed on GitHub. Replace them with resolvable absolute URLs to the canonical SpeakerOps docs, or drop the link markup and reference the paths as plain text.

* [ADRs.md](../../SpeakerOps/docs/ADRs.md)
* [Integration-Strategy.md](../../SpeakerOps/docs/Integration-Strategy.md)

.github/instructions/markdown.instructions.md:191

• This bullet is indented by an extra space, which makes it a nested list item and can trip markdownlint indentation rules (MD005/MD007). Align it with the surrounding top-level list items.

* Follow proper capitalization for product and technology names used in this repository (e.g., "GitHub", "JavaScript").
 * Avoid using inline HTML when a Markdown equivalent exists. If an inline HTML element is necessary and allowed, keep it minimal and well-formed.

• Files reviewed: 13/13 changed files
• Comments generated: 9
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🔵 Needs a closer look

Several documentation and tooling consistency issues (frontmatter-title heading levels, lint rule mismatch, and typos) should be resolved before merging to avoid immediate doc-style drift and avoidable lint noise.

Review details

Suppressed comments (7)

Previously missed (1) — in code that hasn't changed since the last review.

.github/instructions/markdown.instructions.md:191

• This list item is indented by one extra level, which renders it as a nested bullet under the previous rule (and is inconsistent with the rest of the section). Align it with the other top-level bullets.

 * Avoid using inline HTML when a Markdown equivalent exists. If an inline HTML element is necessary and allowed, keep it minimal and well-formed.

.markdownlint.json:10

• The markdownlint config enforces MD004 as asterisk, but multiple Markdown files in this PR (for example, README.md and docs/Integration-Strategy.md) use - list markers; enabling markdownlint with this setting will produce widespread lint errors unrelated to the content of this PR. Consider switching MD004 to consistent so existing documents pass while still preventing mixed markers within a list/file.

  "MD004": {
    "style": "asterisk"
  },

CONTRIBUTING.md:8

• This file has YAML frontmatter with a title: field, so the top-level # heading violates the repo's markdown rules (frontmatter title should serve as the document title). Also, calling the repository a "fully functional product" contradicts the "Documentation-first repository" status stated in README.md.

## Contributing to TalkFolio

This repository is TalkFolio, a fully functional product in the SpeakerOps family of products for managing talk concepts. Contributions should keep the product focused on talk identity, proposal language, catalog metadata, and the relationships that help surface and discover a talk without owning external content lifecycles.

ARCHITECTURE.md:6

• This file has YAML frontmatter with a title: field, so the top-level # heading violates the repo's markdown rules (frontmatter title should serve as the document title).

## TalkFolio Architecture

.github/instructions/markdown.instructions.md:167

• This list item is indented by one extra level, which renders it as a nested bullet under the previous rule (and is inconsistent with the rest of the section). Align it with the other top-level bullets.

* Avoid emphasis within words using underscores; prefer asterisks for word-internal emphasis if absolutely necessary.

.github/instructions/csharp-tests.instructions.md:26

• Typo in the example test name: ExpectedResult_SpecialCoditions should be ExpectedResult_SpecialConditions.

Test method name matches the expected result and, if necessary, any special conditions: `ExpectedResult_SpecialConditions` or `ExpectedResult`.

.github/copilot-instructions.md:5

• Use the correct casing for the language name: c# should be C# (and remove the trailing space to avoid markdownlint/whitespace noise).

* All code will be written in the latest version of C#, targeting .NET 10.

• Files reviewed: 13/13 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

🔵 Needs a closer look

It introduces verifiable documentation and markdownlint-convention inconsistencies (list markers, extra blank line, punctuation, and a maturity claim conflict) that should be corrected before merge.

Review details

Suppressed comments (8)

Previously missed (5) — in code that hasn't changed since the last review.

README.md:79

• New lists in this section use - markers, but .markdownlint.json enables MD004 with asterisk, so these additions will introduce new lint violations. Switch these list items to * to match the configured rule.

This issue also appears on line 83 of the same file.

- file-based Talk and PresentationFamily records that match the documented schema
- validation tooling for schema and cross-record relationships
- migration tooling to pull structured data from the existing notes sources
- basic catalog commands or reports for listing and filtering talks

CONTRIBUTING.md:8

• This file describes the repository as a "fully functional product", but README.md states the repo is still documentation-first and not yet implemented. Aligning this wording avoids implying behavior or maturity that doesn't exist yet.

This repository is TalkFolio, a fully functional product in the SpeakerOps family of products for managing talk concepts. Contributions should keep the product focused on talk identity, proposal language, catalog metadata, and the relationships that help surface and discover a talk without owning external content lifecycles.

CONTRIBUTING.md:64

• This sentence uses curly quotes (� �). The repo's Markdown guidance prefers plain ASCII punctuation, so these should be regular quotes to stay consistent and avoid editor/encoding churn.

This issue also appears on line 112 of the same file.

Prefer small, well-scoped changes. Avoid broad “cleanup” or “improve architecture” tasks without a concrete requirement or failing case.

docs/ADRs.md:162

• There are two consecutive blank lines before the ADR-013 heading (lines 160-161), which violates the configured MD012 maximum of 1 consecutive blank line. Remove one blank line to keep markdownlint clean.

**Rationale:** The product code and the talk catalog have different lifecycles. Keeping the maintained catalog generally external preserves independent versioning and reduces coupling between implementation work and content maintenance.


## ADR-013: Configuration uses standard .NET precedence with in-memory overrides at the top

docs/Integration-Strategy.md:144

• The newly added MVP plan sections use - list markers (for example here), but .markdownlint.json enables MD004 with asterisk. To avoid introducing additional lint failures in the new content, switch these new lists to * markers.

- Choose the on-disk directory layout for Talk and PresentationFamily records.
- Define the file-naming convention for file-backed records.
- Define how the configurable data-root path is supplied.
- Keep maintained catalog data generally outside this repo, while adding dedicated test repositories or fixture datasets here for validation.
- Add sample records that exercise the full schema.

README.md:87

• This list block also uses - markers, but .markdownlint.json configures MD004 to require * list markers. Converting these items avoids adding more markdownlint failures.

- controlled vocabulary source files for Category and TargetAudience
- TalkCircuit-friendly export/read model for proposal submission workflows
- rich editing UI
- authoring scaffolds unless they fall out cheaply from the file format work
- automated external sync

CONTRIBUTING.md:112

• This heading uses curly quotes. The repo's Markdown guidance prefers ASCII punctuation, so use regular quotes here for consistency.

## Boundaries and “do not touch” guidance

.github/instructions/markdown.instructions.md:191

• This bullet is indented by one extra space, which makes it a nested list item and can trigger MD007/MD005 indentation rules. It should be aligned with the surrounding top-level bullets.

 * Avoid using inline HTML when a Markdown equivalent exists. If an inline HTML element is necessary and allowed, keep it minimal and well-formed.

• Files reviewed: 13/13 changed files
• Comments generated: 0 new
• Review effort level: Lite