docs: improve documentation for input/output types

.github/workflows/ci.yaml

@@ -159,8 +159,8 @@ jobs:
               echo "integration=false" >> $GITHUB_OUTPUT
             fi
 
-            # Detect docs changes (includes CLI source which generates docs/cli.md)
-            if echo "$CHANGED" | grep -qE '^(docs/|README\.md|cmd/|pkg/cli/)'; then
+            # Detect docs changes (includes any Markdown file and CLI source which generates docs/cli.md)
+            if echo "$CHANGED" | grep -qE '^(docs/|README\.md|cmd/|pkg/cli/|.*\.md$)'; then
               echo "docs=true" >> $GITHUB_OUTPUT
             else
               echo "docs=false" >> $GITHUB_OUTPUT
@@ -503,6 +503,23 @@ jobs:
       - name: Lint Python
         run: mise run lint:python
 
+  lint-docs:
+    name: Lint Markdown
+    needs: changes
+    if: needs.changes.outputs.docs == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+      - uses: dtolnay/rust-toolchain@stable
+      - run: rustup default stable
+      - uses: taiki-e/install-action@cargo-binstall
+      - uses: jdx/mise-action@v4
+        with:
+          cache: false
+      - name: Lint Markdown
+        run: mise run lint:docs
+
 # =============================================================================
 # Test Jobs
 # =============================================================================
@@ -837,6 +854,7 @@ jobs:
       - lint-rust
       - lint-rust-deny
       - lint-python
+      - lint-docs
       - test-go
       - test-rust
       - test-python
@@ -861,6 +879,7 @@ jobs:
           echo "  lint-rust: ${{ needs.lint-rust.result }}"
           echo "  lint-rust-deny: ${{ needs.lint-rust-deny.result }}"
           echo "  lint-python: ${{ needs.lint-python.result }}"
+          echo "  lint-docs: ${{ needs.lint-docs.result }}"
           echo "  test-go: ${{ needs.test-go.result }}"
           echo "  test-rust: ${{ needs.test-rust.result }}"
           echo "  test-python: ${{ needs.test-python.result }}"
@@ -882,6 +901,7 @@ jobs:
             "${{ needs.lint-rust.result }}" \
             "${{ needs.lint-rust-deny.result }}" \
             "${{ needs.lint-python.result }}" \
+            "${{ needs.lint-docs.result }}" \
             "${{ needs.test-go.result }}" \
             "${{ needs.test-rust.result }}" \
             "${{ needs.test-python.result }}" \

.markdownlint-cli2.yaml

@@ -0,0 +1,14 @@
+globs:
+  - "*.md"
+  - "**/*.md"
+
+ignores:
+  - ".cargo-home/**"
+  - "site/**"
+  - "docs/llms.txt"
+  - "CLAUDE.md"
+
+config:
+  default: false
+  MD009: true
+  MD047: true

AGENTS.md

@@ -4,7 +4,7 @@ This file provides guidance to coding agents when working with code in this repo
 
 ## Project Overview
 
-Cog is a tool that packages machine learning models in production-ready containers. 
+Cog is a tool that packages machine learning models in production-ready containers.
 
 It consists of:
 - **Cog CLI** (`cmd/cog/`) - Command-line interface for building, running, and deploying models, written in Go
@@ -132,7 +132,7 @@ import (
 - **Async**: tokio runtime; async/await patterns
 
 ## Working on the CLI and support tooling
-The CLI code is in the `cmd/cog/` and `pkg/` directories. Support tooling is in the `tools/` directory. 
+The CLI code is in the `cmd/cog/` and `pkg/` directories. Support tooling is in the `tools/` directory.
 
 The main commands for working on the CLI are:
 - `go run ./cmd/cog` - Runs the Cog CLI directly from source (requires wheel to be built first)

DESIGN.md

@@ -21,7 +21,7 @@ We want Cog to be a standard artifact for what a model is and how that model is
 
 There are a few things driving Cog's design:
 
-- **Reproducible artifact**: When you've put your model in Cog, it'll run anywhere, and _keep_ on running. This is why it's a Docker image, with all of the model's dependencies. Docker images have a content-addressable SHA256 ID, which is the identifier for that model's behavior, byte-for-byte. 
+- **Reproducible artifact**: When you've put your model in Cog, it'll run anywhere, and _keep_ on running. This is why it's a Docker image, with all of the model's dependencies. Docker images have a content-addressable SHA256 ID, which is the identifier for that model's behavior, byte-for-byte.
 - **Weights inside the image**: We encourage users to put model weights in images. If the weights are on cloud storage somewhere, then they might change or disappear, and the image will produce different results. There's nothing magical about Docker images – they're just a bundle of files. Docker moves around that bundle of files quite slowly, though, but we can optimize that process so it's as fast as reading weights directly from blob storage, or wherever.
 - **Models are just functions**: Models can be lots of things. We are of the opinion that [machine learning is just software](https://replicate.com/blog/machine-learning-needs-better-tools), and a model is just a function. It often needs to be attached to a GPU, but apart from that it's just a normal function that has some input and some output. This is the core difference between Docker's abstraction and Cog's abstraction: Docker packages up an executable, whereas Cog packages up a _function_.
 - **Standard interface**: When you run the Docker container, it serves an HTTP server, that is a standard API for running that function. You can think of it like a remote procedure call.

crates/coglet-python/README.md

@@ -99,7 +99,7 @@ asyncio event loop (Python)
 └─────────────────────────────────────────────────────────────┘
 ```
 
-**Why single loop?** 
+**Why single loop?**
 - Python asyncio has one event loop per thread
 - We use `run_coroutine_threadsafe` to submit from Rust/Tokio
 - Multiple slots can have concurrent predictions (up to `max_concurrency`)