Clarify installation and update guidance

[lightos]

Summary

• document installation in an isolated virtual environment
• explain why the editable checkout must remain in place for self-update
• warn that the panoptic name on PyPI belongs to an unrelated project
• include the Python 3.10-only tomli dependency
• replace unsafe PyPI update guidance with the official GitHub source archive

Verification

• 270 tests pass
• Ruff, formatting, strict mypy, Markdown lint, and pip-audit pass
• editable installation succeeds on Python 3.10
• official GitHub archive installation succeeds on Python 3.10
• non-editable installs print the official archive update command

Summary by CodeRabbit

• Documentation

  • Expanded installation requirements and workflow, including virtual environment activation and Windows-specific guidance.
  • Clarified how updates work for checkout-based vs archive-based installs.
  • Added clearer instructions for installing from the latest branch archive (including main.zip).

• Bug Fixes

  • Updated displayed upgrade guidance so archive-based refreshes show the exact python -m pip install --upgrade ...main.zip command, and the legacy message is no longer shown.

• Tests

  • Strengthened coverage to assert the exact upgrade command output and ensure the legacy string is not printed.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: ae86ac48-bf23-48cf-98cb-0ee447e3accb

📥 Commits

Reviewing files that changed from the base of the PR and between 92a910d and 1747194.

📒 Files selected for processing (2)

• README.md
• tests/test_update.py

---

Walkthrough

The update workflow now prints a branch-specific GitHub archive installation command for pip-installed setups. Tests verify the exact guidance, while the README documents virtual environment installation and checkout versus archive update behavior.

Changes

Update guidance

Layer / File(s)	Summary
Pip update command and guidance panoptic/update.py, tests/test_update.py	Defines the GitHub archive URL and pip command, uses it in update guidance, and verifies the exact output.
Installation and update documentation README.md	Documents expanded requirements, virtual environment setup, development installation, and separate checkout and archive update paths.

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

Poem

I’m a rabbit with a fresh little zip,
Hopping through updates with one tidy pip.
A venv for my burrow, commands clear and bright,
Git branches or archives now update just right.
Test paws confirm every printed line—
Carrots for code, and the docs all shine!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main changes: clarified installation steps and update instructions in the docs and update flow.
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 docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/install-guidance

---

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

[coderabbitai]

Actionable comments posted: 2

🤖 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 `@README.md`:
- Around line 67-70: Update the Windows virtual-environment activation
instructions in the setup section to document both Command Prompt’s
.venv\Scripts\activate and PowerShell’s .venv\Scripts\Activate.ps1 forms, while
preserving the surrounding editable-install guidance.

In `@tests/test_update.py`:
- Around line 48-49: Update the test containing the PIP_UPDATE_COMMAND
assertions to independently assert the expected GitHub archive command literal
rather than relying on the imported implementation constant. Retain the existing
negative assertion that excludes the legacy “pip install -U panoptic” command.

🪄 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: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: fe2f3a07-9cdb-4ad7-b667-f75b8635184d

📥 Commits

Reviewing files that changed from the base of the PR and between c7dc6d5 and 92a910d.

📒 Files selected for processing (3)

• README.md
• panoptic/update.py
• tests/test_update.py