# Conflicts:
#	crates/tarball/src/lib.rs

main already has an AGENTS.md (added in #268) with content unrelated
to my edits. Removing the duplicate so the merge from main pulls in
that file cleanly; the AI-guide references will be re-added on top.

Brings in the AGENTS.md introduced in #268, along with the recent
performance, refactor, and benchmark work landed since this branch
was started. The local placeholder AGENTS.md was removed in the
preceding commit so the merge takes main's version unmodified.

* docs: fix bugs and typos in CODE_STYLE_GUIDE.md

- Correct push_path/push_back function name mismatch
- Fix non-compiling call sites in the &Path example so the snippet
  type-checks against the stated signature
- Add missing `move` and trailing `;` to tokio::task::spawn examples
  so they compile
- Rename "Cloning an atomic counter" section to "Cloning `Arc` and `Rc`"
  since Arc/Rc are reference counters, not atomic counters
- Fix missing semicolon in an assert_eq! example
- Grammar fixes ("could easily be refactored", "Explicitly marking
  the cloned type aids", "as more pull requests are reviewed")

* docs: add CONTRIBUTING.md and AGENTS.md

Adapted from KSXGitHub/parallel-disk-usage's CONTRIBUTING.md, with
pacquet-specific changes:

- No version-release exception in the commit message convention
- Setup and automated-check sections rewritten around `just init`,
  `just install`, and `just ready` instead of `test.sh`
- Dropped the squashfs/fuse external-dependency section (not relevant
  to pacquet); kept the registry-mock note instead
- Examples reworked to use pacquet types (manifests, store, etc.)
- Cross-links between CONTRIBUTING.md and CODE_STYLE_GUIDE.md so the
  two documents are discovered together

AGENTS.md instructs AI agents to follow both guides.

* docs: pass &mut my_list in push_path examples

Addresses copilot review comment on PR #255: `push_path` takes
`&mut Vec<PathBuf>`, so the call sites need `&mut my_list` rather
than `my_list` to compile.

* chore: temporarily remove AGENTS.md before merging main

main already has an AGENTS.md (added in #268) with content unrelated
to my edits. Removing the duplicate so the merge from main pulls in
that file cleanly; the AI-guide references will be re-added on top.

* docs(agents): point at CONTRIBUTING.md and CODE_STYLE_GUIDE.md

Adds an explicit "Follow the project guides" section near the top of
AGENTS.md and lists CONTRIBUTING.md alongside CODE_STYLE_GUIDE.md in
the repo-layout overview, so both guides are surfaced as required
reading.

* docs: move code-style sections from CONTRIBUTING.md to CODE_STYLE_GUIDE.md

Per option A of the contributing/style split discussion: keep
CONTRIBUTING.md focused on process (commit message format, writing
style, setup, automated checks), and have CODE_STYLE_GUIDE.md own
every code-level convention.

Moved into CODE_STYLE_GUIDE.md (under the existing `## Guides`
section, in thematic order):

- Module Organization
- Import Organization
- Derive Macro Ordering
- Generic Parameter Naming
- Variable and Closure Parameter Naming (with the single-letter rules)
- Trait Bounds
- Pattern Matching
- Using `pipe-trait` (with when-to-use and when-not-to-use)
- Error Handling
- Conditional Test Skipping (`#[cfg]` vs `#[cfg_attr(..., ignore)]`)
- Unit test file layout (was the top-level `## Unit Tests` section)

The intra-doc link from "Where the external file sits" to
"Module Organization" still resolves because both sections now live
in the same file.

Updated `AGENTS.md`'s descriptions for both guides to reflect the new
split. Per the review thread on this PR, no other prose in
`AGENTS.md` was rewritten for writing-style conformance; that is
deferred to the maintainer.

* docs(style): drop "Derive Macro Ordering" section

The codebase does not follow the rules this section prescribed, so
the section was aspirational rather than descriptive of pacquet's
actual conventions:

- "Split across multiple #[derive(...)] lines" — never done. Across
  52 files with derives, zero stack two #[derive(...)] attributes.
- Prescribed standard → comparison → Hash → derive_more order —
  frequently violated. The dominant pattern places Display right
  after Debug (e.g. crates/lockfile/src/comver.rs:8,
  crates/lockfile/src/pkg_ver_peer.rs:12).
- #[cfg_attr(feature = "...", derive(...))] split — zero
  occurrences anywhere in crates/.

The codebase's actual convention is too loose to codify usefully
(one #[derive(...)] line, Debug first when present), so the section
is removed rather than weakened to a near-tautology.

* docs(style): use .filter on both sides of the parameter-naming example

The pair was meant to contrast the closure parameter name (`entry`
vs. `x`), but using `.filter_map` on the good side and `.filter` on
the bad side muddled that with a method-choice difference. The
mismatch was carried over from the upstream parallel-disk-usage
guide. Use `.filter` on both sides so the example isolates the rule
under discussion.

* docs(style): fix four porting quirks in CODE_STYLE_GUIDE.md examples

Sweep for the same class of issue as the .filter / .filter_map
mismatch (#255, KSXGitHub review): examples that were degraded when
ported from upstream parallel-disk-usage.

- show_path with `path: &Path`: passing `my_path_buf` directly
  doesn't compile because `PathBuf` does not auto-coerce to `&Path`
  in argument position. Use `&my_path_buf` (same fix family as the
  earlier push_path call sites).
- "Avoiding deeply nested function calls": the pre-pipe version was
  a single non-nested call, so the rule's motivation wasn't visible.
  Replaced with a genuinely nested constructor chain that piping
  flattens.
- "pipe_as_ref" example lost its contrast in the port; restored the
  "without pipe" companion line so the rule's payoff is shown.
- Picked a custom-looking pacquet function name (is_within_store)
  for that example instead of `Path::exists`, since nobody uses
  `path_buf.pipe_as_ref(Path::exists)` over `path_buf.exists()`.
- Renamed `rows.zip(cols)` to `left_indices.zip(right_indices)` so
  the `(i, j)` closure parameters line up with the rule about index
  variables.

* docs: address review-agent findings on the docs branch

- AGENTS.md: drop the stale "derives" topic from both descriptions
  of CODE_STYLE_GUIDE.md, since the Derive Macro Ordering section
  was removed in 06c08ff for not matching the codebase.
- AGENTS.md: replace the inaccurate "pre-commit checks" wording in
  the repo-layout entry for CONTRIBUTING.md. The pre-push hook only
  runs format checks; the full `just ready` suite is a manual step
  before submitting, not an automated pre-commit hook.
- CODE_STYLE_GUIDE.md: fix subjunctive grammar — "should a test
  fails" should be "should a test fail" (predates the recent move,
  but caught while reviewing the section).

* Revert "docs(style): fix four porting quirks in CODE_STYLE_GUIDE.md examples"

This reverts commit 0d1e434.

* docs(style): make the pipe_as_ref example actually mid-chain

The text says "to pass a reference mid-chain", but the example was
a single `path_buf.pipe_as_ref(Path::exists)` call with no chain at
all. Replaced with a four-step chain that has methods before and
after `pipe_as_ref`, so the rule's wording matches the demonstration.

Audited every other pipe example in the section: each one is either
already part of a chain (dependencies, into_iter, summarize, etc.)
or is intentionally chain-free in the "When NOT to use pipe"
section, so no other rectification was needed.

Addresses KSXGitHub review on PR #255.

* docs(contributing): describe `just install` generically

Replace "Install the registry-mock dependencies" with "Install the
test dependencies". The previous wording named an internal component
(registry-mock) and would drift if `just install` ever did more or
different work. The new wording defers to `just install` as the
source of truth for what gets installed.

Per KSXGitHub review on PR #255.

* docs(style): drop `idx` from the index-naming alternatives

Per @zkochan review on PR #255: reduce the number of alternatives
listed for index variables. Keep `index` and `*_index` (such as
`row_index`); drop `idx`.

Applied to both places where the triple appeared: the "Conventional
single-letter names" bullet and the "Index variables" rule, so the
two stay consistent.

---------

Co-authored-by: Claude <noreply@anthropic.com>