#60: docs: update documentation

[Asifdotexe]

Summary by CodeRabbit

• Documentation
  • Updated repository analysis instructions with current Poetry/Python module commands.
  • Added guidance for analyzing a specific repository.
  • Revised architecture documentation to clarify snapshot periods and historical fossil extraction.
  • Updated DevOps documentation to reflect the current analysis, fossil update, cleanup, and pull request workflows.

[coderabbitai]

📝 Walkthrough

Walkthrough

Documentation now reflects Poetry module entrypoints, repository selection, revised snapshot and fossil extraction terminology, and updated automated and manual workflow behavior.

Changes

Pipeline Documentation

Layer / File(s)	Summary
Poetry module command entrypoints README.md	Analysis and survivor-fossil commands now use Poetry Python module entrypoints, with an optional repository argument for analysis.
Snapshot and fossil extraction model docs/ARCHITECTURE.md	Architecture documentation uses current-period snapshot terminology and describes extracting historical lines from the absolute oldest commit.
CI workflow and persistence flow docs/DEVOPS.md	The documented workflows now cover run_pipeline.py, survivor updates, cleanup, persistence, pull request creation, and manual fossil updates.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• Asifdotexe/Theseus#20: Adds the workflow and survivor-update behavior described by these documentation changes.
• Asifdotexe/Theseus#21: Overlaps with the updated module entrypoints and DevOps workflow documentation.
• Asifdotexe/Theseus#47: Introduces module-mode execution of the documented pipeline runner.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title is generic and doesn't indicate the specific documentation updates in README, ARCHITECTURE, or DEVOPS.	Rename it to mention the main docs change, e.g. 'docs: update pipeline and repository analysis docs'.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 60-docs-update-docs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/ARCHITECTURE.md`:
- Line 51: Update docs/ARCHITECTURE.md lines 51 and 62: rename the SortCommits
diagram step to describe selecting the first non-empty line from the first
alphabetically sorted added file, and explicitly document that files are tried
in alphabetical order, unreadable files are skipped, and the first non-empty
line is returned.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 2ea9e25b-3890-4a6a-821a-c532e3806c83

📥 Commits

Reviewing files that changed from the base of the PR and between 57725f5 and e8a3dd5.

📒 Files selected for processing (3)

• README.md
• docs/ARCHITECTURE.md
• docs/DEVOPS.md

[coderabbitai]

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Document the actual genesis-line selection algorithm.

The implementation does not extract an arbitrary “first line” from the oldest commit: it sorts files added by that commit, reads the first readable file, and returns its first non-empty line.

• docs/ARCHITECTURE.md#L51-L51: Rename the diagram step to reflect selection of the first non-empty line from the first alphabetically sorted added file.
• docs/ARCHITECTURE.md#L62-L62: State the file-order and non-empty-line behavior explicitly to keep the documentation deterministic and accurate.

📍 Affects 1 file

• docs/ARCHITECTURE.md#L51-L51 (this comment)
• docs/ARCHITECTURE.md#L62-L62

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/ARCHITECTURE.md` at line 51, Update docs/ARCHITECTURE.md lines 51 and
62: rename the SortCommits diagram step to describe selecting the first
non-empty line from the first alphabetically sorted added file, and explicitly
document that files are tried in alphabetical order, unreadable files are
skipped, and the first non-empty line is returned.