docs: explain how Consistent Ignores match Snyk Code findings and where they can move

scan-fix-and-prevent/manage-risk/prioritize-issues-for-fixing/ignore-issues/consistent-ignores-for-snyk-code/README.md

@@ -7,7 +7,7 @@ nav_context: classic
 
 # Consistent Ignores for Snyk Code
 
-Snyk Code Consistent Ignores helps your teams focus on important tasks by filtering out distractions. It ensures that once an ignore is created, it is consistently respected regardless of how and where the test is run and what branch is being tested.
+Snyk Code Consistent Ignores helps your teams focus on important tasks by filtering out distractions. After you ignore a finding, Snyk applies the ignore to that finding across the repository: in every branch and integration, in the Snyk CLI and Snyk IDE plugins, and in pull request checks.
 
 By filtering out false positives, inapplicable threats, and accepted risks, your security teams can prioritize fixing real problems, and developers can code without interruptions.
 
@@ -19,6 +19,30 @@ Enable Snyk Code Consistent Ignores for your Group or Organization in the Snyk W
 
 Any ignores created or converted with the feature enabled will not be automatically converted back to Project-based ignores. You can recreate them manually after disabling the feature.
 
+## How Consistent Ignores match findings
+
+Snyk attaches a Consistent Ignore to the repository-level identifier of a finding (`snyk/asset/finding/v1`), not to a file path and line number.
+
+Each time Snyk Code tests the repository, Snyk matches the results to the findings it already tracks for that repository. This applies to tests from every branch, the Snyk CLI, Snyk IDE plugins, and pull request checks. When code moves or changes, Snyk matches the finding to its existing identifier where it can, so the ignore continues to apply.
+
+Snyk Code records file paths relative to the directory that a test starts from, and uses the path as one of the signals when it matches a finding. Tests of one repository that start from different directories report the same file under different paths.
+
+Deleting a branch Project or a target does not delete Consistent Ignores and does not reopen ignored findings. The ignores remain in place for the repository.
+
+## If an ignored finding appears as open again
+
+Snyk cannot always match a finding to the identifier that its ignore is attached to. Two setups cause this most often:
+
+* Tests of one repository that start from different directories, for example the repository root in a pipeline and a module directory on a developer machine.
+* Repositories that contain duplicate copies of their source files, such as a baseline or build output directory.
+
+In these cases, Snyk can attach the ignore to the finding at a different path. The original finding appears as **Open** again, and the finding at the other path is suppressed. Snyk does not move the ignore back automatically. The original ignore is not deleted.
+
+1. [Ignore the finding again](./#create-an-ignore) from its issue card.
+2. [Retest the Project](../../../../scan-with-snyk/snyk-code/manage-code-vulnerabilities/#retesting-code-repository) to update the issue status.
+3. Review ignored findings in duplicate directories, and exclude those directories from tests where possible.
+4. If ignored findings reappear repeatedly, contact Snyk Support with the Organization, the Project, and the URLs of the affected issues.
+
 ## User roles
 
 To create, edit and remove ignores, you need to have a user role assigned with Ignore management permissions. Only Group Admins can set these permissions (see [User role management](https://docs.snyk.io/platform-administration/user-management/user-role-management)).

scan-fix-and-prevent/manage-risk/prioritize-issues-for-fixing/ignore-issues/consistent-ignores-for-snyk-code/snyk-cli.md

@@ -23,6 +23,8 @@ Repository context is required for asset-scoped ignores to take effect. Policy-b
 
 `snyk code test` automatically detects the repository context if a .git directory is present. If not, you can explicitly specify it using the `--remote-repo-url` option. To verify the Git URL, run `git remote -v`.
 
+Run `snyk code test` from the root of the Git repository, without a subdirectory path argument. Snyk records file paths relative to the directory you test, so testing from the root keeps paths consistent with other tests of the repository, such as tests of Projects imported through an SCM integration.
+
 ## Snyk CLI default ignore behavior
 
 The CLI display output hides ignored results by default when you run `snyk code test`. It displays only unignored results and a summary table with the total number of issues (open and ignored).
@@ -43,7 +45,7 @@ You can find the ignore metadata in the suppressions module of the SARIF output.
 
 ## Access the finding identifier in JSON and SARIF output
 
-The finding identifier is included in the JSON and SARIF output of Snyk CLI. To view it, run `snyk code test --json` and navigate to `runs.results[n].fingerprints.snyk/assets/finding/v1` in the JSON output. See How Snyk Code identifies and tracks issues.
+The Snyk CLI includes the finding identifier in its JSON and SARIF output. To view it, run `snyk code test --json` and navigate to `runs[0].results[n].fingerprints["snyk/asset/finding/v1"]` in the JSON output. To learn how Snyk uses this identifier, visit [How Consistent Ignores match findings](./#how-consistent-ignores-match-findings).
 
 You can use this identifier to [create new ignores using API calls](api.md).
 

scan-fix-and-prevent/manage-risk/prioritize-issues-for-fixing/ignore-issues/consistent-ignores-for-snyk-code/snyk-pull-request-checks.md

@@ -15,7 +15,7 @@ If a finding is ignored after a PR check has already been completed, the PR chec
 
 • The inline comment for the ignored finding is collapsed by default and marked as resolved.
 
-Ignores are respected in[ Snyk Code Pull Request Checks](../../../../scan-with-snyk/pull-requests/pull-request-checks/) regardless of whether they are created through [policy](./#manage-ignores-at-the-group-level-through-snyk-code-security-policies) or for an [individual `snyk/assets/finding/v1` value](./#manage-ignores-in-snyk-projects).
+Ignores are respected in[ Snyk Code Pull Request Checks](../../../../scan-with-snyk/pull-requests/pull-request-checks/) regardless of whether they are created through [policy](./#manage-ignores-at-the-group-level-through-snyk-code-security-policies) or for an [individual `snyk/asset/finding/v1` value](./#manage-ignores-in-snyk-projects).
 
 ## Example: Snyk Pull Request Check with ignored finding