Add portfolio management docs

Signed-off-by: nscuro <nscuro@protonmail.com>

Author: nscuro

context/diataxis-contract.md

@@ -71,6 +71,7 @@ correctly and safely.
 - Step-by-step beginner introductions (→ Tutorials).
 - Exhaustive parameter listings (→ Reference).
 - Design rationale or architectural background (→ Concepts).
+- REST endpoints or configuration property keys when the procedure is UI-driven (→ Surface language).
 
 ---
 
@@ -105,6 +106,7 @@ product.
 - Step-by-step instructions (→ Tutorials or Guides).
 - Parameter or API field listings (→ Reference).
 - Actionable procedures ("do X, then Y") (→ Guides).
+- Java field names, REST endpoint paths, or runtime config keys (→ Surface language).
 
 ---
 
@@ -186,3 +188,34 @@ Rules:
 Use relative links between documentation pages. Prefer linking to a specific
 section (`concepts/vulnerability-analysis.md#data-sources`) over linking to an
 entire page when the relevant information is in a subsection.
+
+---
+
+## Surface language
+
+Each Diataxis type has a default surface vocabulary. Match it to the audience
+that consults the page.
+
+- **Concepts**: UI labels and domain terms. Do not use Java field names
+  (`isLatest`, `accessTeams`, `inactiveSince`), REST endpoint paths, or
+  runtime configuration property keys. Refer to features the way they appear
+  in the application. Permission codes and CycloneDX classifier names that
+  surface verbatim in the product (BOMs, dropdowns, badges) are fine.
+- **Guides**: describe procedures via the UI by default. The user's path is
+  the form, the dropdown, the toggle. Inline REST endpoints, request bodies,
+  or configuration property keys only when the page is itself a technical
+  procedure where the API or config file is the user's entry point (for
+  example, "Upload a BOM via REST API", "Configure with environment
+  variables"). Otherwise, link to the relevant Reference subsection and keep
+  prose UI-first.
+- **Reference**: structured tables of UI-visible labels, dropdown values,
+  classifier names, and other product-surface vocabulary belong here. The
+  dedicated REST API and configuration-property references (the OpenAPI
+  specs, the `application.properties` table) are the home for low-level
+  identifiers. Other Reference subsections should also stay UI-first.
+- **Tutorials**: same default as Guides. The student is using the UI unless
+  the tutorial is explicitly an API tutorial.
+
+When a feature has both a UI label and a technical identifier, prefer the UI
+label and link out to Reference for the identifier. The reverse breaks for
+users who never see the API or the config file.

docs/concepts/.pages

@@ -1,6 +1,8 @@
 title: Concepts
 nav:
   - index.md
+  - About projects: projects.md
+  - About tags: tags.md
   - About access control: access-control.md
   - About vulnerability data sources: about-vulnerability-data-sources.md
   - About notifications: notifications.md

docs/concepts/access-control.md

@@ -175,3 +175,5 @@ and holders of `PORTFOLIO_ACCESS_CONTROL_BYPASS` until one is assigned.
 
 * [Permissions reference](../reference/permissions.md) for the full permissions table
   and default teams.
+* [About projects](projects.md) for how Dependency-Track models
+  projects, hierarchies, and collection projects.

docs/concepts/changes-in-v5.md

@@ -111,6 +111,14 @@ shipped as a beta feature in v4 with known gaps and noticeable overhead on
 larger portfolios. v5 closes those gaps and reworks the implementation so
 the cost stays bounded as the project count grows.
 
+### Retention policies for projects and metrics
+
+v5 expires inactive project versions and time-series metrics on
+configurable schedules. v4 left both to grow unbounded, so operators
+carried stale portfolio data and ever-growing metric tables. See
+[Configuring project retention](../guides/administration/configuring-project-retention.md)
+and [time-series metrics retention](time-series-metrics.md#daily-partitions-and-bounded-retention).
+
 ### Centralized secrets
 
 Credentials for integrations live in one place instead of spreading across

docs/concepts/component-policies.md

@@ -59,7 +59,8 @@ dependency graph, or operate on SPDX license expressions directly.
 ## Where a policy applies
 
 By default, a policy applies to every project in the portfolio. Narrow it to specific projects, to
-descendants of those projects, or to projects carrying specific tags. Scoping is flat: a policy
+descendants of those projects, or to projects carrying specific
+[tags](tags.md). Scoping is flat: a policy
 either applies to a project or does not. See
 [Component policies › Assignment](../reference/policies/component-policies.md#assignment) for the
 exact rules.

docs/concepts/projects.md

@@ -0,0 +1,170 @@
+# About projects
+
+A **project** is the unit of tracking in Dependency-Track. Everything else, from components
+to findings to policy violations to metrics, hangs off projects. The **portfolio** is the
+set of all projects in an instance, and how you model it shapes what reports, alerts, and
+aggregations are useful later.
+
+This page explains what a project is, how projects relate to each other, and the deliberate
+limits of the model.
+
+## What a project is
+
+Each project has:
+
+- A name and an optional version that together identify it.
+- A classifier naming the kind of thing the project represents (an app, a library, a
+  container image, a firmware image, and so on, matching CycloneDX). See the
+  [classifier list](../reference/projects.md#classifiers).
+- Optional ecosystem identifiers: a Package URL, a CPE, or a SWID tag.
+- Descriptive metadata such as a group, a description, authors, a supplier, a manufacturer,
+  and external references.
+- Tags (categorical labels) and project properties (typed key-value metadata).
+- An optional parent, forming a hierarchy.
+- An access list controlling which teams can see it.
+- Lifecycle state: an active flag, the timestamp of the last BOM import, the timestamp of
+  the last vulnerability analysis, and the current risk score.
+
+<!-- TODO(screenshot): docs/assets/images/concepts/projects/project-detail-header.png - Project detail header for a regular project at /projects/{uuid}/overview. Show: the version dropdown (closed), the "LATEST VERSION" badge, tag chips, description, and the severity pie charts to anchor the "what defines a project" discussion. -->
+
+## What Dependency-Track does *not* assume
+
+A few modelling decisions are deliberately left to the user. Knowing them up front avoids
+arguments later:
+
+- **Dependency-Track does not prescribe what a project is.** A project can map to a single
+  library, a deployable service, an environment of a service, or an entire product line.
+  Pick the granularity that matches how you triage and report.
+- **Versions are opaque strings.** Dependency-Track does not parse, compare, or sort them.
+  Semver-like ordering is not assumed. The "latest version" pointer is a manually maintained
+  flag (see [Versions](#versions)), not a computed one.
+- **Projects cannot depend on projects.** Component-level dependencies live inside a BOM. The
+  only relationship Dependency-Track tracks between projects is the parent-child hierarchy
+  below, and that hierarchy is organizational, not a dependency graph. If service A consumes
+  service B, that fact is not expressible as a project relation.
+- **A name and version together identify a project globally.** That pair is unique across
+  the entire instance, independent of where the project sits in the hierarchy. The same
+  name and version cannot exist under two different parents.
+
+## Active and inactive projects
+
+A project is **active** by default. Marking it inactive records the time and changes its
+behavior:
+
+- It disappears from active portfolio views unless the viewer opts in to show inactive
+  projects.
+- It cannot serve as a parent.
+- It becomes eligible for retention-driven deletion (see [Retention](#retention)). Active
+  projects never are.
+
+A project with active children cannot become inactive. Mark the children first, or accept
+that the parent stays around for as long as something underneath stays live.
+
+## Hierarchies
+
+A project can have one parent and any number of children. Hierarchies are organizational:
+they let you group by product, environment, team, or any other axis that fits how you work.
+
+Two things flow through the hierarchy:
+
+- **Access control.** A team that can see a parent can also see the parent's descendants.
+  See [Access control](#access-control) below.
+- **Aggregated metrics on collection projects.** A [collection project](#collection-projects) reads
+  metrics from its children to produce its own. Regular parents do not. The risk score on a
+  regular parent reflects only that parent's own components, not its children.
+
+Constraints worth remembering:
+
+- A project cannot be its own ancestor. Dependency-Track rejects cycles.
+- The hierarchy does not affect identity. A name and version pair remains globally unique,
+  so the same combination cannot appear under two different parents.
+
+(Inactive projects cannot serve as a parent either. See [Active and inactive projects](#active-and-inactive-projects).)
+
+<!-- TODO(screenshot): docs/assets/images/concepts/projects/projects-tree-view.png - Projects landing at /projects with "Show flat view" toggled OFF, the tree expanded one level, and at least one collection-project parent visible. Show: the portfolio as a hierarchy and the calculator icon that distinguishes a collection project from a regular parent. -->
+
+## Collection projects
+
+A **collection project** is a parent whose only role is to combine metrics from its
+children. It holds no components or services of its own. Instead, it surfaces the metrics
+of its children using one of three modes:
+
+| Mode                       | Behavior                                                            |
+|:---------------------------|:--------------------------------------------------------------------|
+| Roll up every direct child | Combines metrics from every direct child.                           |
+| Roll up by tag             | Combines metrics from direct children carrying a chosen tag.        |
+| Roll up the latest version | Combines metrics from direct children marked as the latest version. |
+
+Collection projects are useful for product or portfolio aggregations that span versions,
+services, or environments without forcing every child to share a tag scheme. They differ
+from regular parents in three important ways:
+
+- They have no classifier. The classifier field disappears once a project becomes a
+  collection project.
+- They cannot have components, services, or a dependency graph. The detail page hides those
+  tabs and shows a *Collection Projects* tab listing children instead.
+- They do not accept BOM uploads.
+
+For when to reach for which mode and how to set them up, see
+[Organizing projects into hierarchies](../guides/user/organizing-projects.md).
+
+<!-- TODO(screenshot): docs/assets/images/concepts/projects/collection-project-header.png - Project detail header for a collection project, hovering the calculator icon so the tooltip showing the configured logic is visible. Show: how a collection project surfaces in the UI and that the regular Components / Services / Dependency Graph tabs are absent (Collection Projects tab is present instead). -->
+
+## Versions
+
+Two or more projects can share a name. Together they represent the version history of one
+logical thing. A *latest version* flag marks one of them as current. At most one version
+per name carries the flag.
+
+The latest-version flag drives:
+
+- The latest-version collection mode.
+- The badge URLs that resolve a project by name without specifying a version.
+- The *LATEST VERSION* badge in the project header.
+
+Because Dependency-Track does not parse version strings, nothing here is automatic. You
+set the flag manually when promoting a release. Cloning a project produces a new sibling
+with chosen inclusions (components, services, tags, properties, audit history, access list,
+policy violations) and is the typical path for starting a new version. See
+[Managing project versions](../guides/user/managing-project-versions.md).
+
+## Tags and properties
+
+A project carries two kinds of metadata. A **tag** is a categorical label that many
+projects can share. Policies, alerts, the tag-filtered collection mode, and the project
+list filter all read tags. For the wider model see [About tags](tags.md). A **project
+property** is a typed key-value pair (group, name, value, type, optional description)
+scoped to one project. The policy engine, alerting, and collection logic do not consult
+properties. Use a tag for a label that may apply to many projects, and a property for
+per-project structured data you want to read back later.
+
+## Retention
+
+By default, inactive projects stick around indefinitely. When the operator turns on
+retention, a scheduled maintenance task deletes inactive projects according to one of two
+policies:
+
+- **By age**: delete inactive projects older than a configured cutoff.
+- **By version count**: keep the most recent N inactive versions per name, and delete the
+  rest.
+
+Active projects are never touched. See
+[Configuring project retention](../guides/administration/configuring-project-retention.md).
+
+## Access control
+
+Each project has an access list. A team can see a project when:
+
+- The team appears on that project's access list, **or** on the access list of the
+  project's ancestors. Granting a team access to a parent also grants access to every
+  descendant.
+- The team holds the `PORTFOLIO_ACCESS_CONTROL_BYPASS` permission, which overrides the
+  access list entirely.
+
+Use this when designing a hierarchy: shared access concerns sit at parents, and the
+children inherit them automatically. To revoke inherited access, remove the team from
+the ancestor that granted it. A descendant cannot opt out on its own.
+
+For the wider model (users, teams, and which permissions gate which actions), see
+[About access control](access-control.md) and the
+[Permissions reference](../reference/permissions.md).

docs/concepts/tags.md

@@ -0,0 +1,53 @@
+# About tags
+
+A **tag** is a short, shared label. You can attach the same tag to
+[projects](projects.md), [component](component-policies.md) and
+[vulnerability](vulnerability-policies.md) policies, vulnerabilities, and
+[alerts](notifications.md), and the rest of the system reads tags to scope behavior.
+Tags are deliberately lightweight: a name and nothing else.
+
+## What a tag is
+
+A tag is just a name. Names are unique across the instance, so two attachments of the
+same name refer to the same tag. A tag has no value, no type, no namespace, no
+description. If you need richer metadata bound to a project, use
+[project properties](projects.md#tags-and-properties) instead.
+
+Tags are many-to-many with the things they label. A project can carry many tags, and a
+tag can label many projects. Removing a tag from one project does not affect any other.
+
+## What tags do
+
+Tags are a scoping primitive. Different parts of the system look at the same tag set:
+
+- **Project filtering.** The project list can filter by tag.
+- **Policy assignment.** A component or vulnerability policy can target only projects
+  carrying specific tags. See [About component policies](component-policies.md) and
+  [About vulnerability policies](vulnerability-policies.md).
+- **Collection projects.** The tag-based collection mode aggregates only the children
+  carrying the configured tag. See
+  [About projects › Collection projects](projects.md#collection-projects).
+- **Alerts.** An [alert](notifications.md) can fire only for projects carrying specific tags.
+- **Vulnerability tagging.** You can attach tags to vulnerabilities for triage and
+  reporting.
+
+## Tags versus project properties
+
+Both attach metadata to a project, but they answer different questions:
+
+- Reach for a **tag** when the value is a label that may apply to many projects, and you
+  expect the policy engine, alerting, or the tag-filtered collection mode to read it.
+- Reach for a **project property** when the value is per-project structured data (a
+  typed key with a value) that you want to read back later, but no built-in feature
+  consumes it.
+
+Properties carry types and group names, while tags do not. If you find yourself encoding two
+pieces of information into one tag (`team:platform`, `env=prod`), that is a signal to
+reach for a property, or for two separate tags, instead.
+
+## Lifecycle
+
+Tags come into being implicitly on first use. Attaching a name that does not exist
+creates the tag. Detaching the last attachment leaves an orphan tag, which the
+maintenance task cleans up on its next run. Tags carry no per-tag access control. Any
+user who can edit a project can also tag it.

docs/concepts/vulnerability-policies.md

@@ -22,8 +22,8 @@ rather than replace them. The important differences are:
 
 * **VEX analyses are static.** A VEX statement records a decision for a specific finding at a specific
   moment. Vulnerability policies are rules. A single policy can match many findings now and in
-  the future, based on conditions such as component version ranges, project tags, or dependency graph
-  relationships.
+  the future, based on conditions such as component version ranges,
+  [project tags](tags.md), or dependency graph relationships.
 * **VEX cannot express constraints.** A policy condition can say "apply this decision only while the
   affected component sits behind a specific transitive dependency" or "only for projects tagged
   `3rd-party`". VEX cannot do this.

docs/guides/administration/.pages

@@ -14,6 +14,7 @@ nav:
   - configuring-oidc.md
   - managing-notification-templates.md
   - debugging-notifications.md
+  - configuring-project-retention.md
   - backing-up.md
   - upgrading-instances.md
   - migrating-from-v4.md