docs: add the full documentation surface — AGENTS, CONTRIBUTING, cli and development references

Assisted-by: DeepSeek V4 Flash

docs/ARCHITECTURE.md

@@ -2,6 +2,8 @@
 
 How gasm-devkit is put together and why.
 
+Repository: [sourcedock.dev/petrbalvin/gasm-devkit](https://sourcedock.dev/petrbalvin/gasm-devkit)
+
 ## Design goals
 
 1. **A real AST, not a grammar hack.**  The linter, analyser, assembler and
@@ -309,6 +311,18 @@ The `gasm verify` CLI subcommand exposes this: it loads a file, reports the
 available functions and (with `-smoke`) calls each NOSPLIT function with zeroed
 arguments to confirm the trampoline round-trips.
 
+### `debug`
+
+The interactive debugger (Phase 4, linux/amd64).  It launches the target
+function in a child process that maps the JIT code, calls
+`PTRACE_TRACEME`, and stops; the parent attaches via ptrace and controls
+execution.  Breakpoints are patched as INT3 bytes through `/proc/pid/mem`
+(PTRACE_PEEKTEXT is unreliable with Go's multi-threaded runtime).
+The child pins its goroutine to the OS thread with `runtime.LockOSThread`
+so the traced thread is the one executing JIT code.  The REPL provides
+single-step, register inspection, label resolution, and breakpoint
+management.
+
 ## Extension points
 
 - **New architecture:** add an entry to the generator in `_gen`, run