1 files changed, 52 insertions, 0 deletions
diff --git a/docs/developer-guide.org b/docs/developer-guide.org
new file mode 100644
index 0000000..df3199f
--- /dev/null
+++ b/docs/developer-guide.org
@@ -0,0 +1,52 @@
+#+TITLE: DUET Developer Guide
+#+AUTHOR: Craig Jennings
+
+* Status
+
+Stub. Fills out across the implementation phases; the backend API and
+transfer-spec contract land with Phase 2/3, the full release checklist with
+Phase 10. The authoritative design is [[file:design/duet-spec.org][docs/design/duet-spec.org]].
+
+* Repository layout
+
+- =duet.el= — the package. Public =duet-= commands and pure =duet--= helpers.
+  The only file that ships (Eask =package-file=).
+- =tests/= — ERT suites, one =test-duet-<area>.el= per source area, plus the
+  shared harness (=test-bootstrap.el=, =check-deps.el=, =run-coverage-file.el=).
+- =scripts/= — developer tooling, not part of the package: =coverage-summary.el=
+  (terminal coverage report) and =duet-complexity.el= (the McCabe gate).
+- =docs/= — this guide and the design spec.
+
+* Building and testing
+
+DUET uses [[https://emacs-eask.github.io/][Eask]] for dependency management and a Makefile for the common
+loops. From the project root:
+
+#+begin_src shell
+make deps          # Emacs Lisp deps (eask) + transport CLIs (rsync/rclone/lftp/unison)
+make setup         # Emacs Lisp deps only
+make test          # full ERT suite (excludes :slow)
+make test-file FILE=complexity   # one file
+make test-name TEST=pattern      # ERT name selector
+make compile       # byte-compile, warnings-as-errors
+make lint          # elisp-lint
+make coverage      # undercover + simplecov JSON, then a terminal summary
+make complexity    # cyclomatic-complexity report, gated on the soft budget
+make doctor        # transport executables present + duet loads
+make test-live     # env-gated live remote tests (DUET_LIVE_TESTS)
+#+end_src
+
+* Complexity budget
+
+=make complexity= runs =scripts/duet-complexity.el=, a homegrown McCabe branch
+counter (no off-the-shelf tool measures Emacs Lisp). The budget is soft: a
+function above the threshold (default 10) is split or carries a written
+justification. The target is advisory — run it on demand; it is not part of
+=make test=.
+
+* Backend API
+
+To be written with Phase 2. The published seam is =duet-register-backend=; the
+stable surface is the classified-endpoint plist, the =duet-backend= struct, the
+=duet-transfer-spec= plist, and the transfer-event payload. See the spec's
+"Backend extension API and developer contract".