docs: polish v0.1.0 release materials

Author: stacknil

README.md

@@ -1,7 +1,17 @@
 # systems-foundations
 
-Training ground for Linux and systems foundations projects.
+`systems-foundations` is a training repository for small, reviewable labs around Linux and systems fundamentals.
 
-## Projects
+The goal is to keep each lab narrow, deterministic, and easy to inspect end to end: input evidence, normalization, filtering, reporting, and notes that explain the basics without pretending to be a full platform.
 
-- `projects/linux-auth-observe`: deterministic mini-lab for normalizing and reviewing Linux auth evidence.
+## Current Mini-Lab
+
+- `projects/linux-auth-observe`
+
+`linux-auth-observe` is the first mini-lab in the repository. It focuses on Linux auth evidence from exported journald JSON lines plus distro auth syslog files, normalizes them into JSONL, supports simple filtering, and produces a Markdown summary report.
+
+## Repository Shape
+
+- `projects/`: focused mini-labs
+- `notes/`: short learning notes and schemas that support the labs
+- `.codex/`: local assistant configuration for this repository

docs/release-v0.1.0.md

@@ -0,0 +1,44 @@
+# v0.1.0 Release Notes
+
+## Title
+
+First Credible Mini-Lab
+
+## Summary
+
+`systems-foundations` now has its first focused mini-lab: `projects/linux-auth-observe`.
+
+This release packages a narrow, tested workflow for Linux auth evidence review:
+
+- normalize supported journald and auth syslog fixtures into JSONL
+- filter normalized rows by `user`, `IP`, and `service`
+- generate a Markdown summary report
+- optionally emit structured parse failures as JSONL during normalization
+
+## Included in v0.1.0
+
+- support for exported journald JSON lines
+- support for Ubuntu or Debian `auth.log`
+- support for RHEL or CentOS `secure`
+- normalized JSONL output with preserved raw evidence
+- CLI workflow for `normalize`, `filter`, and `summary`
+- pytest coverage for parsing, CLI behavior, summary generation, golden regression, and syslog year rollover
+
+## Validation Snapshot
+
+- `pytest -q` passes in the current repository state
+- current tests cover all three supported fixture families
+- current tests cover `Dec 31 -> Jan 1` syslog rollover behavior
+- current tests cover optional `--error-output` generation for malformed lines
+
+## Not in Scope
+
+- `audit.log`
+- real-time monitoring or tailing
+- databases or storage backends
+- packaging or publishing workflows
+
+## Notes
+
+- Syslog timestamps are yearless and timezone-less in the source files, so v0.1.0 documents and tests the current year inference and rollover rules explicitly
+- `_PID` is preserved as contextual metadata when present, not as a standalone identity guarantee

projects/linux-auth-observe/README.md

@@ -2,33 +2,69 @@
 
 `linux-auth-observe` is a small deterministic mini-lab for normalizing Linux auth evidence into JSONL, filtering it, and generating a short Markdown report.
 
-## Scope
-
-- Supported inputs in v0.1:
-  - `journalctl --output=json` line-delimited exports
-  - Ubuntu or Debian `auth.log`
-  - RHEL or CentOS `secure`
-- Supported outputs:
-  - normalized JSONL
-  - filtered JSONL to stdout
-  - Markdown summary report
-- Not included in v0.1:
-  - `audit.log`
-  - real-time tailing
-  - databases
-  - packaging or publishing workflows
-
-## Quickstart
+## Supported Inputs
+
+- `journalctl --output=json` line-delimited exports
+- Ubuntu or Debian `auth.log`
+- RHEL or CentOS `secure`
+
+## Non-Goals
+
+- `audit.log`
+- real-time tailing or monitoring
+- databases or storage layers
+- packaging or publishing workflows
+
+## Validation Status
+
+- `pytest -q` currently passes for parser behavior, filtering, summary generation, CLI workflow, golden regression checks, and syslog year-rollover coverage
+- `normalize` is covered against the three supported fixture families
+- `filter` is covered for `user`, `IP`, and `service` constraints
+- `summary` is covered for readable Markdown output
+- `error-output` is covered as an optional JSONL artifact for parse failures during batch normalization
+
+## Assumptions
+
+- Syslog inputs are line-oriented and follow a standard auth/syslog prefix with no embedded year
+- Syslog timestamps are interpreted in a chosen timezone, defaulting to `local`
+- If `--year` is provided, it anchors the first syslog record and later `Dec -> Jan` transitions roll forward into the next year
+- If `--year` is omitted, the parser infers the starting year from the first syslog record relative to the current time in the chosen timezone; if the first record would land more than about half a year in the future, it is treated as the previous year
+- Journal inputs are one JSON object per line and map from `MESSAGE`, `_PID`, `_COMM`, and `_SYSTEMD_UNIT` when available
+- `_PID` is preserved as contextual process metadata when present; it should not be read as a guaranteed identity anchor on its own
+- Unsupported or malformed records fail clearly per line without stopping the full batch
+
+## End-to-End Workflow
 
 ```bash
 python -m pip install -e .[dev]
-python -m linux_auth_observe normalize --input tests/fixtures/ubuntu_auth.log --source auto --year 2026 --timezone Asia/Shanghai --output output/events.jsonl
-python -m linux_auth_observe filter --input output/events.jsonl --user alice --ip 192.0.2.10 --service sshd
-python -m linux_auth_observe summary --input output/events.jsonl --output output/summary.md
-python -m pytest -q
+
+python -m linux_auth_observe normalize \
+  --input tests/fixtures/ubuntu_auth.log \
+  --source auto \
+  --year 2026 \
+  --timezone Asia/Shanghai \
+  --output output/events.jsonl
+
+python -m linux_auth_observe filter \
+  --input output/events.jsonl \
+  --user alice \
+  --ip 192.0.2.10 \
+  --service sshd
+
+python -m linux_auth_observe summary \
+  --input output/events.jsonl \
+  --output output/summary.md
+
+python -m linux_auth_observe normalize \
+  --input tests/fixtures/ubuntu_auth_with_error.log \
+  --source auto \
+  --year 2026 \
+  --timezone Asia/Shanghai \
+  --output output/events.jsonl \
+  --error-output output/parse-errors.jsonl
 ```
 
-`normalize` defaults to the current UTC year and the local system timezone when parsing yearless syslog timestamps. Pass `--year` and `--timezone` to replay fixtures deterministically.
+The intended flow is `normalize -> filter -> summary`, with `--error-output` available when you want a structured JSONL artifact for parse failures while the batch continues.
 
 ## Event Schema