Create foundation

[nscuro]

Adds a foundation for the new documentation page, based on Material for MkDocs.

Includes linters for YAML, Markdown, and prose to ensure consistency across multiple contributors, and to help guide agents for AI-assisted contributions.

[github-advanced-security]

You are seeing this message because GitHub Code Scanning has recently been set up for this repository, or this pull request contains the workflow file for the Code Scanning tool.

What Enabling Code Scanning Means:

• The 'Security' tab will display more code scanning analysis results (e.g., for the default branch).
• Depending on your configuration and choice of analysis tool, future pull requests will be annotated with code scanning analysis results.
• You will be able to see the analysis results for the pull request's branch on this overview once the scans have completed and the checks have passed.

For more information about GitHub Code Scanning, check out the documentation.

[Copilot]

Pull request overview

Adds an initial MkDocs Material–based documentation site scaffold (Diataxis structure), along with containerized local workflows and CI lint/build/deploy automation.

Changes:

• Add MkDocs configuration, section scaffolding pages, and Diataxis/context guidance files.
• Introduce containerized Makefile targets for serve/build and Markdown/YAML/prose linting (Vale).
• Add GitHub Actions workflows for lint/build/deploy and repository automation configs (Dependabot, zizmor).

Reviewed changes

Copilot reviewed 41 out of 48 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
source/README.md	Notes source/ directory purpose for symlinked repos.
source/.gitkeep	Keeps source/ in the repo.
requirements.txt	Adds pinned, hashed Python dependency lock for docs tooling/plugins.
requirements.in	Declares top-level MkDocs plugin dependencies.
mkdocs.yml	Configures MkDocs Material site, plugins, and Markdown extensions.
existing-docs/README.md	Notes existing-docs/ directory purpose for v4 docs symlink.
existing-docs/.gitkeep	Keeps existing-docs/ in the repo.
docs/index.md	Adds home page content and top-level navigation links.
docs/.pages	Defines top-level nav ordering via awesome-pages.
docs/tutorials/index.md	Adds Tutorials section landing page.
docs/tutorials/.pages	Defines Tutorials section nav.
docs/guides/index.md	Adds Guides section landing page.
docs/guides/.pages	Defines Guides section nav.
docs/guides/upgrading/index.md	Adds Upgrading subsection landing page.
docs/concepts/index.md	Adds Concepts section landing page.
docs/concepts/.pages	Defines Concepts section nav.
docs/reference/index.md	Adds Reference section landing page.
docs/reference/.pages	Defines Reference section nav.
docs/includes/abbreviations.md	Adds shared abbreviations for MkDocs abbr extension.
docs/blog/index.md	Adds Blog section landing page.
docs/blog/.authors.yml	Adds author metadata for blog plugin.
docs/blog/posts/test-post.md	Adds draft test post to validate blog integration.
docs/blog/posts/.gitkeep	Keeps blog posts directory in the repo.
context/briefing.md	Adds product/audience briefing context for contributors/agents.
context/diataxis-contract.md	Defines Diataxis rules and writing constraints.
context/source-inventory.md	Documents repo symlink map and legacy-docs accuracy notes.
context/vocabulary.md	Adds canonical terminology list for consistent docs language.
context/workflows.md	Adds placeholder for user workflow scaffolding.
README.md	Adds contributor-facing instructions (make targets, structure, linting).
Makefile	Adds Docker-based targets for lock/build/serve and linting.
Dockerfile	Defines dev image layering MkDocs Material + locked requirements.
.dockerignore	Controls Docker build context contents.
AGENTS.md	Adds agent/contributor instructions and repo conventions.
.yamllint.yml	Adds yamllint configuration and excludes.
.markdownlint-cli2.yaml	Adds markdownlint-cli2 configuration and ignores.
.vale.ini	Configures Vale styles/packages and per-path overrides.
.vale/styles/config/vocabularies/DependencyTrack/accept.txt	Adds accepted vocabulary terms for Vale.
.vale/styles/config/vocabularies/DependencyTrack/reject.txt	Adds reject list placeholder for Vale vocabulary.
.vale/styles/DependencyTrack/EmDash.yml	Adds Vale rule to discourage em-dashes.
.vale/styles/DependencyTrack/AITransitions.yml	Adds Vale rule discouraging weak AI-like transitions.
.vale/styles/DependencyTrack/AIFillerPhrases.yml	Adds Vale rule discouraging filler phrases.
.vale/styles/DependencyTrack/AIBuzzwords.yml	Adds Vale rule discouraging buzzwords.
.gitignore	Ignores site output, caches, downloaded Vale styles, symlink dirs, IDE files.
.idea/icon.svg	Adds IDE icon asset (kept despite .idea ignore).
.github/workflows/docs.yml	Adds CI lint/build and deploy-to-pages (mike) workflow.
.github/workflows/zizmor.yml	Adds zizmor workflow for GitHub Actions security scanning.
.github/dependabot.yml	Adds Dependabot update configuration for pip/docker/actions.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.