feat: initial markkit project structure

.agents/skills/process-issues/SKILL.md

@@ -0,0 +1,52 @@
+Process open GitHub issues and resolve them via merged pull requests.
+
+## Qualifying Issues
+
+Only process issues created by authorized users or containing approval
+comments from those users.
+
+## Core Principle
+
+One issue = one PR. No bundling. No skipping.
+
+## Process Per Issue
+
+### 1. Understand & Scope
+- Read the issue thoroughly
+- Classify: bug, feature, docs, refactor
+- Identify affected crates and files
+- Create branch: `fix/issue-{N}-{short-slug}`
+
+### 2. Test First
+- For bugs: create a failing test that reproduces the issue
+- For features: scaffold validation tests
+- Place tests alongside existing test modules
+
+### 3. Implement
+- Make minimal, focused changes
+- Cover positive and negative test cases
+- Consider security implications for parsing changes
+
+### 4. Ship
+- Use the `/ship` skill for:
+  - Spec updates
+  - Quality gates
+  - PR creation
+  - CI verification
+  - Merge
+
+### 5. Return to Main
+```bash
+git checkout main && git pull origin main
+```
+Then proceed to next issue.
+
+## Post-Resolution
+
+After all issues are resolved, identify any `#[ignore]` tests
+that now pass and un-ignore them in a single PR.
+
+## Arguments
+
+Optional: specific issue numbers or labels.
+Default: process all qualifying open issues.

.agents/skills/ship/SKILL.md

@@ -0,0 +1,51 @@
+Run the full ship flow: verify quality, ensure test coverage, update
+artifacts, smoke test, then push, create PR, and merge when CI is green.
+
+## Phases
+
+### 1. Pre-flight
+- Verify on a feature branch (not main)
+- Check for uncommitted changes
+- Fetch latest main and rebase if needed
+
+### 2. Test Coverage
+- Identify changed code paths
+- Ensure tests exist for:
+  - Positive cases (happy path)
+  - Negative cases (errors, edge cases)
+  - Security scenarios (malicious input)
+- Add missing tests
+
+### 3. Artifact Updates
+- Update specs if behavior changed
+- Update CHANGELOG.md for user-facing changes
+- Update documentation for API changes
+
+### 4. Simplification
+- Remove dead code introduced by changes
+- Reduce duplication
+- Simplify where possible without changing behavior
+
+### 5. Security Review
+- Check for injection risks in new parsing code
+- Verify resource limits are enforced
+- Review input validation
+
+### 6. Smoke Test
+- Run `just test` for full test suite
+- Run `just lint` for code quality
+- Build CLI and verify basic extraction works
+
+### 7. Quality Gates
+- `cargo fmt --all -- --check`
+- `cargo clippy --workspace -- -D warnings`
+- `cargo deny check`
+
+### 8. Push, PR, Merge
+- Push branch to remote
+- Create or update PR with summary
+- Wait for CI to pass
+- Merge when green
+
+**IMPORTANT**: Phases 2-5 (tests, artifacts, simplification, security review,
+smoke testing) are the quality core — do NOT skip them.

.claude/commands/maintain.md

@@ -0,0 +1,49 @@
+Run pre-release maintenance checks on the markkit codebase.
+
+Each section below is an outcome to achieve, not a script to follow.
+Use whatever tools and approaches make sense to verify and fix.
+
+Fix issues as you find them — don't just report. Use conventional
+commit messages for any fixes.
+
+Sections (run all unless $ARGUMENTS specifies a subset):
+
+## 1. Dependencies
+- Run `cargo update` and verify tests pass
+- Check for outdated dependencies
+- Review Dependabot PRs if any
+
+## 2. Security
+- Run `cargo audit` for vulnerabilities
+- Run `cargo deny check` for license compliance
+- Review any new advisories
+
+## 3. Tests
+- Run full test suite: `just test`
+- Check coverage isn't regressing
+- Identify any `#[ignore]` tests that should be re-enabled
+
+## 4. Documentation
+- Verify README is current
+- Check rustdoc builds without warnings
+- Ensure specs match implementation
+
+## 5. Examples
+- Verify examples compile and run
+- Update examples for any API changes
+
+## 6. Specs
+- Review specs/ for accuracy
+- Update implementation status
+
+## 7. Simplification
+- Look for dead code, unused dependencies
+- Identify duplication opportunities
+- Reduce complexity where possible
+
+## 8. CI Health
+- Check recent GitHub Actions runs
+- Verify nightly builds are passing
+- Review any flaky tests
+
+Deliver a summary of findings and actions taken.

.claude/hooks/fix-git-identity.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# SessionStart hook: override agent-like git identity with real user
+
+set -euo pipefail
+
+git rev-parse --git-dir >/dev/null 2>&1 || exit 0
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+source "$REPO_ROOT/scripts/lib/common.sh"
+
+configure_commit_git_identity_if_needed 2>/dev/null || true

.claude/settings.json

@@ -0,0 +1,20 @@
+{
+  "gitAttribution": false,
+  "attribution": {
+    "commit": "",
+    "pr": ""
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/fix-git-identity.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

.claude/skills

@@ -0,0 +1 @@
+../../.agents/skills

.github/dependabot.yml

@@ -0,0 +1,25 @@
+version: 2
+updates:
+  # Rust dependencies
+  - package-ecosystem: "cargo"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "chore(deps)"
+    groups:
+      rust-dependencies:
+        patterns:
+          - "*"
+
+  # GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "chore(ci)"
+    groups:
+      github-actions:
+        patterns:
+          - "*"

.github/workflows/ci.yml

@@ -0,0 +1,73 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+env:
+  CARGO_TERM_COLOR: always
+  RUSTFLAGS: -Dwarnings
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+      - uses: Swatinem/rust-cache@v2
+      - name: Check formatting
+        run: cargo fmt --all -- --check
+      - name: Clippy
+        run: cargo clippy --workspace --all-targets -- -D warnings
+      - name: Build docs
+        run: cargo doc --workspace --no-deps
+        env:
+          RUSTDOCFLAGS: -Dwarnings
+
+  audit:
+    name: Audit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - name: Install cargo-audit
+        run: cargo install cargo-audit
+      - name: Install cargo-deny
+        run: cargo install cargo-deny
+      - name: Security audit
+        run: cargo audit
+      - name: License and dependency check
+        run: cargo deny check
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - name: Run tests
+        run: cargo test --workspace
+      - name: Run tests (all features)
+        run: cargo test --workspace --all-features
+
+  check:
+    name: Check
+    needs: [lint, audit, test]
+    runs-on: ubuntu-latest
+    if: always()
+    steps:
+      - name: All jobs passed
+        run: |
+          if [[ "${{ needs.lint.result }}" != "success" ]] || \
+             [[ "${{ needs.audit.result }}" != "success" ]] || \
+             [[ "${{ needs.test.result }}" != "success" ]]; then
+            echo "One or more jobs failed"
+            exit 1
+          fi

.github/workflows/coverage.yml

@@ -0,0 +1,25 @@
+name: Coverage
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  coverage:
+    name: Code Coverage
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - name: Install cargo-tarpaulin
+        run: cargo install cargo-tarpaulin
+      - name: Generate coverage
+        run: cargo tarpaulin --workspace --out xml
+      - name: Upload coverage
+        uses: codecov/codecov-action@v4
+        with:
+          file: cobertura.xml
+          fail_ci_if_error: false

.github/workflows/js.yml

@@ -0,0 +1,28 @@
+name: JavaScript
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "crates/markkit-js/**"
+      - "crates/markkit/**"
+  pull_request:
+    branches: [main]
+    paths:
+      - "crates/markkit-js/**"
+      - "crates/markkit/**"
+
+jobs:
+  build:
+    name: Build Node.js bindings
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - name: Install dependencies
+        run: cd crates/markkit-js && npm install
+      - name: Build
+        run: cd crates/markkit-js && npx napi build --release

.github/workflows/nightly.yml

@@ -0,0 +1,21 @@
+name: Nightly
+
+on:
+  schedule:
+    - cron: "0 4 * * *"
+  workflow_dispatch:
+
+jobs:
+  nightly:
+    name: Nightly checks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@nightly
+        with:
+          components: rustfmt, clippy
+      - uses: Swatinem/rust-cache@v2
+      - name: Build on nightly
+        run: cargo build --workspace
+      - name: Test on nightly
+        run: cargo test --workspace