docs: improve release-facing documentation

Author: stacknil

CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable user-visible changes should be recorded here.
+
+## Unreleased
+
+### Added
+
+- None yet.
+
+### Changed
+
+- None yet.
+
+### Fixed
+
+- None yet.
+
+### Docs
+
+- None yet.
+
+## v0.1.0
+
+### Added
+
+- Parser support for `syslog_legacy` and `journalctl_short_full` authentication log input.
+- Rule-based detections for SSH brute force, multi-user probing, and sudo burst activity.
+- Parser coverage telemetry including parsed/unparsed counts and unknown-pattern buckets.
+
+### Changed
+
+- Established deterministic Markdown and JSON reporting for the MVP release.
+
+### Fixed
+
+- None.
+
+### Docs
+
+- Added CI, CodeQL, repository hardening guidance, and release-facing project documentation for the first public release.

README.md

@@ -7,6 +7,10 @@ C++20 defensive log analysis CLI for Linux authentication logs, with parser cove
 
 It parses `auth.log` / `secure`-style syslog input and `journalctl --output=short-full`-style input, normalizes authentication evidence, applies configurable rule-based detections, and emits deterministic Markdown and JSON reports.
 
+## Project Status
+
+LogLens is an MVP / early release. The repository is suitable for public review, local experimentation, and extension, but parser coverage and rule coverage are intentionally narrow.
+
 ## Why this project exists
 
 Many small security tools can detect a handful of known log patterns. Fewer tools make their parsing limits visible.
@@ -25,15 +29,14 @@ LogLens is a defensive, public-safe repository.
 It is intended for log parsing, detection experiments, and engineering practice.
 It does not provide exploitation, persistence, credential attack automation, or live offensive capability.
 
-
 ## Repository Checks
 
 LogLens includes two minimal GitHub Actions workflows:
 
 - `CI` builds and tests the project on `ubuntu-latest` and `windows-latest`
 - `CodeQL` runs GitHub code scanning for C/C++ on pushes, pull requests, and a weekly schedule
 
-Both workflows are intended to stay stable enough to require on pull requests to `main`. The repository hardening note is in [`docs/repo-hardening.md`](./docs/repo-hardening.md).
+Both workflows are intended to stay stable enough to require on pull requests to `main`. Release-facing documentation is split across [`CHANGELOG.md`](./CHANGELOG.md), [`docs/release-process.md`](./docs/release-process.md), and the repository's GitHub release notes.
 
 ## Threat Model
 
@@ -100,6 +103,31 @@ The CLI writes:
 
 into the output directory you provide. If you omit the output directory, the files are written into the current working directory.
 
+## Sample Output
+
+For sanitized sample input, see [`assets/sample_auth.log`](./assets/sample_auth.log) and [`assets/sample_journalctl_short_full.log`](./assets/sample_journalctl_short_full.log).
+
+`report.md` summary excerpt:
+
+```markdown
+## Summary
+- Input mode: syslog_legacy
+- Parsed events: 14
+- Findings: 3
+- Parser warnings: 2
+```
+
+`report.json` summary excerpt:
+
+```json
+{
+  "input_mode": "syslog_legacy",
+  "parsed_event_count": 14,
+  "finding_count": 3,
+  "warning_count": 2
+}
+```
+
 The config file schema is intentionally small and strict:
 
 ```json
@@ -161,54 +189,15 @@ Tue 2026-03-10 08:18:05 UTC example-host sshd[2238]: Failed publickey for invali
 Tue 2026-03-10 08:31:18 UTC example-host sshd[2245]: Connection closed by authenticating user alice 203.0.113.51 port 51291 [preauth]
 ```
 
-## Example Output
-
-`report.md` excerpt:
-
-```markdown
-# LogLens Report
-
-## Summary
-- Input mode: syslog_legacy
-- Assume year: 2026
-- Timezone present: false
-- Total lines: 16
-- Parsed lines: 14
-- Unparsed lines: 2
-- Parse success rate: 87.50%
-- Parsed events: 14
-- Findings: 3
-- Parser warnings: 2
-```
-
-`report.json` excerpt:
-
-```json
-{
-  "tool": "LogLens",
-  "input_mode": "syslog_legacy",
-  "assume_year": 2026,
-  "timezone_present": false,
-  "parser_quality": {
-    "total_lines": 16,
-    "parsed_lines": 14,
-    "unparsed_lines": 2,
-    "parse_success_rate": 0.8750
-  },
-  "parsed_event_count": 14,
-  "finding_count": 3
-}
-```
-
 ## Known Limitations
 
-- `syslog_legacy` mode requires an explicit year; LogLens no longer guesses one implicitly.
-- `journalctl_short_full` parsing currently supports `UTC`, `GMT`, `Z`, and numeric timezone offsets such as `+0000` or `+00:00`, not arbitrary timezone abbreviations.
-- The parser supports a small set of common `sshd`, `sudo`, and `pam_unix` patterns from `auth.log` or `secure`, not every distro-specific variant.
-- Unsupported lines are surfaced as parser telemetry and warnings only; they do not generate detector findings on their own.
-- `pam_unix` auth failures remain lower-confidence by default; they influence detectors only if `auth_signal_mappings` explicitly upgrades them.
-- Detector thresholds and auth signal mappings are configurable only through the fixed `config.json` schema shown above; partial overrides and alternative config formats are not supported.
-- Findings are intentionally rule-based and conservative; they are not attribution or incident verdicts.
+- `syslog_legacy` requires an explicit year; LogLens does not guess one implicitly.
+- `journalctl_short_full` currently supports `UTC`, `GMT`, `Z`, and numeric timezone offsets, not arbitrary timezone abbreviations.
+- Parser coverage is intentionally narrow and focused on common `sshd`, `sudo`, and `pam_unix` variants.
+- Unsupported lines are surfaced as parser telemetry and warnings, not as detector findings.
+- `pam_unix` auth failures remain lower-confidence by default unless signal mappings explicitly upgrade them.
+- Detector configuration uses a fixed `config.json` schema rather than partial overrides or alternate config formats.
+- Findings are rule-based triage aids, not incident verdicts or attribution.
 
 ## Future Roadmap
 

docs/release-process.md

@@ -0,0 +1,18 @@
+# Release Process
+
+## Changelog Discipline
+
+- Add user-visible changes to `CHANGELOG.md` as they land.
+- Keep entries under `Unreleased` until a version is cut.
+- Use the stable categories `Added`, `Changed`, `Fixed`, and `Docs`.
+- Move `Unreleased` entries into a versioned section during release prep.
+
+## Where Information Belongs
+
+- `README.md`: what the tool is, how to build and run it, sample output, and current limitations.
+- `CHANGELOG.md`: concise version-by-version history of user-visible changes.
+- GitHub release notes: a short release announcement built from the changelog, with highlights and upgrade context.
+
+## Practical Rule
+
+If a change affects external readers or users, it should usually touch either `README.md`, `CHANGELOG.md`, or both.