refactor: consume docusaurus and md

.github/workflows/docs-build.yml → .github/workflows/docusaurus-build.yml

@@ -1,5 +1,5 @@
 ---
-name: Docs Build
+name: Docusaurus Build
 
 on:
   pull_request:
@@ -18,4 +18,4 @@ jobs:
       - name: Fetch justfiles
         run: just fetch
       - name: Test build website
-        run: just docs::build
+        run: just docusaurus-build

.github/workflows/docs-deploy.yml → .github/workflows/docusaurus-deploy.yml

@@ -1,5 +1,5 @@
 ---
-name: Deploy to GitHub Pages
+name: Docusaurus Deploy
 
 on:
   push:
@@ -23,7 +23,7 @@ jobs:
       - name: Fetch justfiles
         run: just fetch
       - name: Build website
-        run: just docs::build
+        run: just docusaurus-build
 
       # Popular action to deploy to GitHub Pages:
       # Docs: https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-docusaurus

.github/workflows/docs-lint.yml → .github/workflows/docusaurus-lint.yml

@@ -1,5 +1,5 @@
 ---
-name: Docs Lint
+name: Docusaurus Lint
 
 on:
   push:
@@ -17,5 +17,5 @@ jobs:
         uses: extractions/setup-just@v4
       - name: Fetch justfiles
         run: just fetch
-      - name: Lint docs
-        run: just docs::fmt-check
+      - name: Lint the site
+        run: just docusaurus-fmt-check

.github/workflows/markdown-lint.yml

@@ -0,0 +1,22 @@
+---
+name: Markdown Lint
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Install just
+        uses: extractions/setup-just@v4
+      - name: Fetch justfiles
+        run: just fetch
+      - name: Lint markdown
+        run: just md-fmt-check

AI_POLICY.md

@@ -2,64 +2,60 @@
 
 The osapi-io project has strict rules for AI usage:
 
-- **All AI usage in any form must be disclosed.** You must state
-  the tool you used (e.g. Claude Code, Cursor, Amp) along with
-  the extent that the work was AI-assisted.
+- **All AI usage in any form must be disclosed.** You must state the tool you
+  used (e.g. Claude Code, Cursor, Amp) along with the extent that the work was
+  AI-assisted.
 
-- **The human-in-the-loop must fully understand all code.** If you
-  can't explain what your changes do and how they interact with the
-  greater system without the aid of AI tools, do not contribute
-  to this project.
+- **The human-in-the-loop must fully understand all code.** If you can't explain
+  what your changes do and how they interact with the greater system without the
+  aid of AI tools, do not contribute to this project.
 
 - **Issues and discussions can use AI assistance but must have a full
-  human-in-the-loop.** This means that any content generated with AI
-  must have been reviewed _and edited_ by a human before submission.
-  AI is very good at being overly verbose and including noise that
-  distracts from the main point. Humans must do their research and
-  trim this down.
-
-- **No AI-generated media is allowed (art, images, videos, audio, etc.).**
-  Text and code are the only acceptable AI-generated content, per the
-  other rules in this policy.
-
-- **Bad AI drivers will be denounced** People who produce bad contributions
-  that are clearly AI (slop) will be added to our public denouncement list.
-  This list will block all future contributions. Additionally, the list
-  is public and may be used by other projects to be aware of bad actors.
-  We love to help junior developers learn and grow, but
-  if you're interested in that then don't use AI, and we'll help you.
-  I'm sorry that bad AI drivers have ruined this for you.
-
-These rules apply only to outside contributions to osapi-io. Maintainers
-are exempt from these rules and may use AI tools at their discretion;
-they've proven themselves trustworthy to apply good judgment.
+  human-in-the-loop.** This means that any content generated with AI must have
+  been reviewed _and edited_ by a human before submission. AI is very good at
+  being overly verbose and including noise that distracts from the main point.
+  Humans must do their research and trim this down.
+
+- **No AI-generated media is allowed (art, images, videos, audio, etc.).** Text
+  and code are the only acceptable AI-generated content, per the other rules in
+  this policy.
+
+- **Bad AI drivers will be denounced** People who produce bad contributions that
+  are clearly AI (slop) will be added to our public denouncement list. This list
+  will block all future contributions. Additionally, the list is public and may
+  be used by other projects to be aware of bad actors. We love to help junior
+  developers learn and grow, but if you're interested in that then don't use AI,
+  and we'll help you. I'm sorry that bad AI drivers have ruined this for you.
+
+These rules apply only to outside contributions to osapi-io. Maintainers are
+exempt from these rules and may use AI tools at their discretion; they've proven
+themselves trustworthy to apply good judgment.
 
 ## There are Humans Here
 
 Please remember that osapi-io is maintained by humans.
 
-Every discussion, issue, and pull request is read and reviewed by
-humans (and sometimes machines, too). It is a boundary point at which
-people interact with each other and the work done. It is rude and
-disrespectful to approach this boundary with low-effort, unqualified
-work, since it puts the burden of validation on the maintainer.
+Every discussion, issue, and pull request is read and reviewed by humans (and
+sometimes machines, too). It is a boundary point at which people interact with
+each other and the work done. It is rude and disrespectful to approach this
+boundary with low-effort, unqualified work, since it puts the burden of
+validation on the maintainer.
 
-In a perfect world, AI would produce high-quality, accurate work
-every time. But today, that reality depends on the driver of the AI.
-And today, most drivers of AI are just not good enough. So, until either
-the people get better, the AI gets better, or both, we have to have
-strict rules to protect maintainers.
+In a perfect world, AI would produce high-quality, accurate work every time. But
+today, that reality depends on the driver of the AI. And today, most drivers of
+AI are just not good enough. So, until either the people get better, the AI gets
+better, or both, we have to have strict rules to protect maintainers.
 
 ## AI is Welcome Here
 
-osapi-io is written with plenty of AI assistance, and many maintainers
-embrace AI tools as a productive tool in their workflow. As a project,
-we welcome AI as a tool!
+osapi-io is written with plenty of AI assistance, and many maintainers embrace
+AI tools as a productive tool in their workflow. As a project, we welcome AI as
+a tool!
 
-**Our reason for the strict AI policy is not due to an anti-AI stance**,
-but instead due to the number of highly unqualified people using AI.
-It's the people, not the tools, that are the problem.
+**Our reason for the strict AI policy is not due to an anti-AI stance**, but
+instead due to the number of highly unqualified people using AI. It's the
+people, not the tools, that are the problem.
 
-I include this section to be transparent about the project's usage about
-AI for people who may disagree with it, and to address the misconception
-that this policy is anti-AI in nature.
+I include this section to be transparent about the project's usage about AI for
+people who may disagree with it, and to address the misconception that this
+policy is anti-AI in nature.