refactor(manifest): update default resource type to rootpath

Change the default resource type from "res" to "rootpath" when no specific
pattern matches in get_local_resource_type. This aligns with the addition
of new documentation resources in the manifest file and improves resource
type detection for root-level paths.

MANIFEST.usm

@@ -11,7 +11,13 @@
     "vapi:usm.vapi": "as-expected",
     "typelib:usm-1.0.typelib": "as-expected",
     "gir:usm-1.0.gir": "as-expected",
-    "pc:usm.pc": "as-expected"
+    "pc:usm.pc": "as-expected",
+    "res:slopdocs/structure.usm.manifest.packaging.md": "source:slopdocs/structure.usm.manifest.packaging.md",
+    "res:slopdocs/structure.usm.manifest.md": "source:slopdocs/structure.usm.manifest.md",
+    "res:slopdocs/structure.usm.manifest.resource-types.md": "source:slopdocs/structure.usm.manifest.resource-types.md",
+    "res:slopdocs/structure.usm.manifest.executable-scripts.md": "source:slopdocs/structure.usm.manifest.executable-scripts.md",
+    "res:slopdocs/structure.usm.manifest.dependency-management.md": "source:slopdocs/structure.usm.manifest.dependency-management.md",
+    "res:slopdocs/utility.usm.manifest.autoprovides.md": "source:slopdocs/utility.usm.manifest.autoprovides.md"
   },
   "depends": {
     "runtime": [

slopdocs/structure.usm.manifest.dependency-management.md

@@ -0,0 +1,314 @@
+# USM Dependency Management
+
+## Overview
+USM manages dependencies through resource references organized by lifecycle phase. Dependencies are specified in the `depends` section of MANIFEST.usm and validated before package operations.
+
+## Dependency Categories
+
+### runtime
+Resources required for the package to function when installed.
+
+**Used for**: Shared libraries, runtime binaries, data files
+**Checked during**: Installation, dependency resolution
+**Example**:
+```json
+"runtime": [
+  "lib:libc.so.6",
+  "lib:libglib-2.0.so",
+  "lib:libgio-2.0.so",
+  "res:common-themes"
+]
+```
+
+### build
+Resources required to compile the package from source.
+
+**Used for**: Compilers, build tools, development libraries
+**Checked during**: Build operations
+**Example**:
+```json
+"build": [
+  "bin:gcc",
+  "bin:make",
+  "pc:glib-2.0.pc",
+  "inc:glib-2.0",
+  "vapi:gio-2.0.vapi"
+]
+```
+
+### manage
+Resources required to run management scripts (build, install, remove).
+
+**Used for**: Shell interpreters, system utilities
+**Checked during**: All script executions
+**Example**:
+```json
+"manage": [
+  "bin:bash",
+  "bin:coreutils",
+  "bin:findutils"
+]
+```
+
+### acquire
+Resources required to download and extract source code.
+
+**Used for**: Download tools, archive utilities
+**Checked during**: Source acquisition
+**Optional**: Only required when `execs.acquire` is specified
+**Example**:
+```json
+"acquire": [
+  "bin:bash",
+  "bin:wget",
+  "bin:tar",
+  "bin:gzip"
+]
+```
+
+## Resource Reference Format
+
+All dependencies use the format `[resource-type]:[resource-name]`:
+
+### Common Runtime Dependencies
+```json
+{
+  "runtime": [
+    "lib:libssl.so.1.1",
+    "lib:libcrypto.so.1.1",
+    "lib:libz.so.1",
+    "cfg:ssl/certs/ca-certificates.crt"
+  ]
+}
+```
+
+### Common Build Dependencies
+```json
+{
+  "build": [
+    "bin:gcc",
+    "bin:pkg-config",
+    "pc:openssl.pc",
+    "pc:zlib.pc",
+    "inc:openssl.h",
+    "inc:zlib.h"
+  ]
+}
+```
+
+### Development Libraries
+```json
+{
+  "build": [
+    "pc:glib-2.0.pc",
+    "pc:gtk-4.pc",
+    "inc:glib-2.0.h",
+    "inc:gtk-4.h",
+    "vapi:gtk-4.vapi"
+  ],
+  "runtime": [
+    "lib:libglib-2.0.so",
+    "lib:libgtk-4.so"
+  ]
+}
+```
+
+## Dependency Resolution
+
+### Validation Process
+USM validates dependencies by:
+1. Parsing resource references
+2. Checking system paths for resource existence
+3. Verifying accessibility and permissions
+4. Reporting missing dependencies
+
+### Resolution Order
+Dependencies are resolved in this priority:
+1. System standard locations
+2. Environment variable overrides
+3. Package manager databases
+4. User-specified paths
+
+### Error Handling
+When dependencies are missing:
+- Build operations fail with detailed error messages
+- Installation operations list all unsatisfied dependencies
+- Script execution fails before starting
+
+## Language-Specific Dependencies
+
+### C Projects
+```json
+{
+  "build": [
+    "bin:gcc",
+    "bin:make",
+    "pc:libname.pc"
+  ],
+  "runtime": [
+    "lib:libname.so"
+  ]
+}
+```
+
+### Vala Projects
+```json
+{
+  "build": [
+    "bin:valac",
+    "pc:glib-2.0.pc",
+    "pc:gobject-2.0.pc",
+    "vapi:glib-2.0.vapi"
+  ],
+  "runtime": [
+    "lib:libglib-2.0.so",
+    "lib:libgobject-2.0.so"
+  ]
+}
+```
+
+### Meson Projects
+```json
+{
+  "build": [
+    "bin:meson",
+    "bin:ninja",
+    "bin:pkg-config"
+  ],
+  "manage": [
+    "bin:bash"
+  ]
+}
+```
+
+### CMake Projects
+```json
+{
+  "build": [
+    "bin:cmake",
+    "bin:make",
+    "bin:pkg-config"
+  ],
+  "manage": [
+    "bin:bash"
+  ]
+}
+```
+
+## System Integration
+
+### Package Manager Integration
+USM can integrate with system package managers for dependency resolution:
+- Check system package databases
+- Install missing dependencies when authorized
+- Track package manager installations
+
+### Cross-Platform Dependencies
+USM handles different system layouts:
+- Linux distributions with varying directory structures
+- Different library naming conventions
+- Architecture-specific dependencies
+
+### Virtual Dependencies
+Some resource types provide virtual dependencies:
+- `bin:sh` - Any POSIX shell
+- `bin:cc` - Any C compiler
+- `lib:libc.so.6` - Standard C library
+
+## Best Practices
+
+### Minimal Dependencies
+- Specify only required dependencies
+- Avoid unnecessary build dependencies
+- Separate runtime and build dependencies clearly
+- Use specific version requirements when needed
+
+### Dependency Accuracy
+- Test dependency specifications
+- Verify all required resources are listed
+- Check for missing transitive dependencies
+- Validate resource references
+
+## Common Patterns
+
+### GUI Applications
+```json
+{
+  "runtime": [
+    "lib:libgtk-4.so",
+    "lib:libgdk_pixbuf-2.0.so",
+    "lib:libpango-1.0.so",
+    "res:shared-mime-info",
+    "res:hicolor-icon-theme"
+  ],
+  "build": [
+    "bin:gcc",
+    "pc:gtk-4.pc",
+    "bin:pkg-config"
+  ]
+}
+```
+
+### Command Line Tools
+```json
+{
+  "runtime": [
+    "lib:libreadline.so",
+    "lib:libncurses.so"
+  ],
+  "build": [
+    "bin:gcc",
+    "inc:readline",
+    "inc:ncurses"
+  ],
+  "manage": [
+    "bin:bash"
+  ]
+}
+```
+
+### Libraries
+```json
+{
+  "build": [
+    "bin:gcc",
+    "bin:pkg-config",
+    "pc:glib-2.0.pc"
+  ],
+  "runtime": [
+    "lib:libglib-2.0.so"
+  ],
+  "provides": [
+    "lib:libmylib.so",
+    "inc:mylib.h",
+    "pc:mylib.pc"
+  ]
+}
+```
+
+## Troubleshooting
+
+### Missing Dependencies
+Common causes and solutions:
+- Incorrect resource type: Verify type matches system location
+- Wrong resource name: Check exact filename/version
+- Path issues: Ensure standard directories are accessible
+- Permission problems: Verify file access rights
+
+### Dependency Conflicts
+When multiple packages provide same resource:
+- Use specific version requirements
+- Specify alternative dependencies
+- Check package manager conflicts
+- Consider virtual dependencies
+
+### Circular Dependencies
+Avoid circular dependency chains:
+- Review dependency graph
+- Split packages if necessary
+- Use optional dependencies
+- Reorganize package structure
+
+---
+
+This guide provides comprehensive information for managing USM package dependencies effectively.

slopdocs/structure.usm.manifest.executable-scripts.md

@@ -0,0 +1,247 @@
+# USM Executable Scripts Reference
+
+## Overview
+USM packages use executable scripts to handle different phases of package lifecycle. Scripts are defined in the `execs` section of MANIFEST.usm and receive specific arguments based on their purpose.
+
+## Script Types
+
+### build
+Required script that compiles source code into binaries.
+
+**Arguments**: `[build-directory]`
+- `build-directory`: Path where build output should be placed
+
+**Environment Variables**:
+- `USM_DESTDIR`, `USM_PREFIX`, `USM_BINDIR`, etc. are set
+
+**Example**:
+```bash
+#!/bin/bash
+set -e
+
+build_dir=$1
+
+cd ${build_dir}
+meson setup ${src_dir} --prefix=${PREFIX} --libdir=${LIBDIR}
+ninja
+```
+
+### install
+Optional script that installs built files to destination directory.
+
+**Arguments**: `[build-directory] [install-directory] [install-type]`
+- `build-directory`: Path containing build output
+- `install-directory`: Path where files should be installed (DESTDIR)
+- `install-type`: "fresh", "upgrade", or "downgrade"
+
+**Environment Variables**:
+- `DESTDIR` is overridden to install-directory
+- Other USM variables are available
+
+**Example**:
+```bash
+#!/bin/bash
+set -e
+
+build_dir=$1
+install_dir=$2
+install_type=$3
+
+cd ${build_dir}
+meson install --destdir ${install_dir}
+```
+
+### postInstall
+Optional script that runs after USM installs resources to system.
+
+**Arguments**: `[build-directory] [install-type]`
+- `build-directory`: Path containing build output
+- `install-type`: "fresh", "upgrade", or "downgrade"
+
+**Use Case**: System integration, cache generation, service registration
+
+**Example**:
+```bash
+#!/bin/bash
+set -e
+
+build_dir=$1
+install_type=$2
+
+# Update desktop database
+update-desktop-database
+
+# Update icon cache
+gtk-update-icon-cache -f -t /usr/share/icons/hicolor
+```
+
+### remove
+Optional script that runs before USM removes package resources.
+
+**Arguments**: `[remove-type]`
+- `remove-type`: "final", "upgrade", or "downgrade"
+
+**Use Case**: Cleanup, service stopping, data preservation
+
+**Example**:
+```bash
+#!/bin/bash
+set -e
+
+remove_type=$1
+
+# Stop service if being upgraded
+if [ "$remove_type" != "final" ]; then
+    systemctl stop myapp || true
+fi
+
+# Remove user data only on final removal
+if [ "$remove_type" = "final" ]; then
+    rm -rf /var/lib/myapp
+fi
+```
+
+### acquire
+Optional script that downloads and extracts source code.
+
+**Arguments**: None
+**Working Directory**: Package root directory
+
+**Use Case**: Projects without native USM support, repository packaging
+
+**Dependencies**: Listed in `depends.acquire` section
+
+**Example**:
+```bash
+#!/bin/bash
+set -e
+
+ARCHIVE_URL="https://github.com/example/myapp/archive/v1.0.0.tar.gz"
+ARCHIVE_NAME="source.tar.gz"
+EXTRACT_DIR="."
+
+echo "Downloading source..."
+wget -O ${ARCHIVE_NAME} ${ARCHIVE_URL}
+
+echo "Extracting archive..."
+tar -xzf ${ARCHIVE_NAME} --strip-components=1
+
+echo "Cleaning up..."
+rm ${ARCHIVE_NAME}
+```
+
+## Script Requirements
+
+### Permissions
+All scripts must be executable:
+```bash
+chmod +x scripts/build.sh
+```
+
+### Error Handling
+Scripts should:
+- Use `set -e` to exit on errors
+- Return appropriate exit codes
+- Handle cleanup on failure
+
+### Environment Variables
+USM sets these variables for all scripts:
+- `USM_DESTDIR`: Destination directory
+- `USM_PREFIX`: Installation prefix
+- `USM_BINDIR`: Binary directory
+- `USM_INCLUDEDIR`: Include directory
+- `USM_DATADIR`: Data directory
+- `USM_INFODIR`: Info directory
+- `USM_LIBDIR`: Library directory
+- `USM_MANDIR`: Manual directory
+- `USM_LIBEXECDIR`: Libexec directory
+- `USM_LOCALEDIR`: Locale directory
+- `USM_LOCALSTATEDIR`: Local state directory
+- `USM_SBINDIR`: System binary directory
+- `USM_SHAREDSTATEDIR`: Shared state directory
+- `USM_SYSCONFIGDIR`: Configuration directory
+- `USM_TAGSDIR`: Tags directory
+
+## Script Locations
+
+Scripts can be placed anywhere in the package, but common conventions:
+- `scripts/`: Directory at package root
+- `usm-scripts/`: Directory at package root
+- Package root: For simple packages
+
+## Build System Integration
+
+### Meson
+```bash
+#!/bin/bash
+set -e
+
+src_dir=$(pwd)
+build_dir=$1
+
+cd ${build_dir}
+meson setup ${src_dir} --prefix=${PREFIX} --libdir=${LIBDIR} --bindir=${BINDIR} --includedir=${INCLUDEDIR}
+ninja
+```
+
+### Make
+```bash
+#!/bin/bash
+set -e
+
+src_dir=$(pwd)
+build_dir=$1
+
+cd ${build_dir}
+make PREFIX=${PREFIX} LIBDIR=${LIBDIR}
+```
+
+### CMake
+```bash
+#!/bin/bash
+set -e
+
+src_dir=$(pwd)
+build_dir=$1
+
+cd ${build_dir}
+cmake ${src_dir} -DCMAKE_INSTALL_PREFIX=${PREFIX} -DCMAKE_INSTALL_LIBDIR=${LIBDIR}
+make
+```
+
+## Progress Reporting
+
+When using `ninjaStyleProgress` flag, USM parses build output for progress:
+- Looks for pattern: `[current/total]`
+- Updates progress bar accordingly
+- Requires build system to output this format
+
+## Best Practices
+
+### Script Design
+- Keep scripts focused on single responsibility
+- Use absolute paths when available
+- Handle all required arguments
+- Validate environment before execution
+
+### Error Handling
+- Check for required dependencies
+- Validate input arguments
+- Provide meaningful error messages
+- Clean up temporary files on exit
+
+### Portability
+- Use POSIX-compliant shell syntax
+- Avoid bash-specific features when possible
+- Test on target systems
+- Consider different directory layouts
+
+### Security
+- Validate input parameters
+- Use secure temporary directories
+- Avoid command injection vulnerabilities
+- Follow principle of least privilege
+
+---
+
+This reference provides complete specification for USM executable scripts used throughout package lifecycle management.

slopdocs/structure.usm.manifest.md

@@ -0,0 +1,222 @@
+# MANIFEST.usm Reference
+
+## Overview
+MANIFEST.usm is a JSON file that defines the structure, metadata, and behavior of a USM software package. This document provides a complete reference for all manifest fields.
+
+## Required Fields
+
+### name
+Type: string
+The package identifier without spaces.
+```json
+"name": "my-package"
+```
+
+### version
+Type: string
+Semantic version with optional package version suffix.
+```json
+"version": "1.2.3+1"
+```
+
+### summary
+Type: string
+Short description of the package.
+```json
+"summary": "A sample package for demonstration"
+```
+
+### licences
+Type: array of license objects
+List of licenses applicable to the package.
+
+Each license object contains:
+- `name` (string): License name
+- `category` (string): License category ("libre", "open-source", "source-available", "proprietary")
+- `text` (string): Path to license file relative to manifest
+
+```json
+"licences": [
+  {
+    "name": "GPLv3",
+    "category": "libre",
+    "text": "LICENSE"
+  }
+]
+```
+
+### provides
+Type: object
+Resources provided by the package. Keys are resource references, values are file specifications.
+
+```json
+"provides": {
+  "bin:myapp": "as-expected",
+  "lib:libmyapp.so": "as-expected",
+  "inc:myapp.h": {"pathBase": "source", "path": "include/myapp.h", "type": "reg"}
+}
+```
+
+### depends
+Type: object
+Package dependencies organized by category.
+
+- `runtime` (array): Runtime dependencies
+- `build` (array): Build-time dependencies  
+- `manage` (array): Management dependencies
+- `acquire` (array, optional): Source acquisition dependencies
+
+```json
+"depends": {
+  "runtime": ["lib:libc.so.6", "lib:libglib-2.0.so"],
+  "build": ["bin:gcc", "pc:glib-2.0.pc"],
+  "manage": ["bin:bash"]
+}
+```
+
+### execs
+Type: object
+Executable scripts for different package lifecycle phases.
+
+- `build` (string, required): Build script path
+- `install` (string, optional): Install script path
+- `remove` (string, optional): Removal script path
+- `postInstall` (string, optional): Post-install script path
+- `acquire` (string, optional): Source acquisition script path
+
+```json
+"execs": {
+  "build": "scripts/build.sh",
+  "install": "scripts/install.sh",
+  "acquire": "scripts/acquire.sh"
+}
+```
+
+### flags
+Type: array of strings
+Package behavior flags.
+
+- `"buildInSourceTree"`: Build in source directory
+- `"setManifestPropertyEnvs"`: Set manifest properties as environment variables
+- `"ninjaStyleProgress"`: Parse Ninja-style progress output
+
+```json
+"flags": ["ninjaStyleProgress"]
+```
+
+## Optional Fields
+
+### md
+Type: string
+Path to markdown description file relative to manifest root.
+```json
+"md": "DESCRIPTION.md"
+```
+
+### url
+Type: string
+Project website or repository URL.
+```json
+"url": "https://github.com/example/my-package"
+```
+
+### screenshots
+Type: array of strings
+Paths to screenshot files relative to manifest root.
+```json
+"screenshots": ["screenshot1.png", "screenshot2.png"]
+```
+
+### icon
+Type: string
+Path to package icon file relative to manifest root.
+```json
+"icon": "my-package.svg"
+```
+
+### metainfo
+Type: string
+Path to AppStream metainfo file relative to manifest root.
+```json
+"metainfo": "my-package.appdata.xml"
+```
+
+### git
+Type: object
+Git repository information.
+- `origin` (string): Repository URL
+- `commit` (string): Commit hash, tag, or branch
+
+```json
+"git": {
+  "origin": "https://github.com/example/my-package",
+  "commit": "v1.2.3"
+}
+```
+
+### extras
+Type: object
+Additional custom properties.
+```json
+"extras": {
+  "customField": "customValue",
+  "buildSystem": "cmake"
+}
+```
+
+## File Specification Objects
+
+When using object notation in `provides`, files can be specified with:
+
+### pathBase
+Base location for the file:
+- `"source"`: Extracted source directory
+- `"build"`: Build output directory
+- `"install"`: Install destination directory
+- `"as-expected"`: Standard system location
+
+### path
+File path relative to pathBase. Empty string when pathBase is "as-expected".
+
+### type
+File system entry type:
+- `"reg"`: Regular file
+- `"dir"`: Directory
+- `"lnk"`: Symbolic link
+
+### dest
+Destination path for symbolic links (required when type is "lnk").
+
+### keepOn
+Array of conditions when resource should not be deleted:
+- `"final"`: During final uninstallation
+- `"upgrade"`: During package upgrade
+- `"downgrade"`: During package downgrade
+
+### skipFor
+Array of conditions when resource should not be installed:
+- `"fresh"`: During fresh installation
+- `"upgrade"`: During package upgrade
+- `"downgrade"`: During package downgrade
+
+## Shorthand Notation
+
+Files can be specified using shorthand notation:
+- `"as-expected"`: Standard location
+- `"build:path/to/file"`: From build directory
+- `"source:path/to/file"`: From source directory
+- `"install:path/to/file"`: From install directory
+
+## Validation Rules
+
+USM validates manifests for:
+- All required fields present
+- Valid JSON syntax
+- Correct license categories
+- Valid resource references
+- Proper file specification objects
+- Semantic version format compliance
+
+---
+
+This reference provides complete specification for MANIFEST.usm files used by USM packages.

slopdocs/structure.usm.manifest.packaging.md

@@ -0,0 +1,121 @@
+# USM Package Maintainer Guide
+
+## Overview
+USM (Universal Source Manifest) is a JSON-based package management system that defines software packages through manifest files. This guide provides package maintainers with comprehensive information for creating and managing MANIFEST.usm files.
+
+## Package Structure
+
+A USM package consists of:
+- `MANIFEST.usm`: JSON manifest file at the project root
+- `scripts/`: Directory containing executable scripts (optional)
+- Source code and project files
+
+## Creating a New Package
+
+### Using Scaffold Templates
+USM provides scaffold templates to quickly create new packages:
+
+```bash
+usm scaffold <package-name> <template> [attributes...]
+```
+
+Available templates:
+- `basic`: Creates only MANIFEST.usm
+- `makefile`: Adds make build system support
+- `meson`: Adds Meson build system support
+
+Attributes:
+- `vala`: Add Vala language dependencies
+- `c`: Add C language dependencies
+- `acquire`: Add source acquisition support
+
+### Manual Manifest Creation
+Create `MANIFEST.usm` at the project root with required fields:
+- `name`: Package identifier (no spaces)
+- `version`: Semantic version with optional package version
+- `summary`: Short description
+- `licences`: Array of license objects
+- `provides`: Resources provided by the package
+- `depends`: Package dependencies
+- `execs`: Executable scripts
+- `flags`: Package behavior flags
+
+## Package Management Workflow
+
+### Building Packages
+```bash
+usm manifest build <build-path>
+```
+
+### Installing Packages
+```bash
+usm manifest install <build-path>
+```
+
+### Creating Complete Packages
+```bash
+usm manifest package
+```
+
+This creates a `.usmc` (USM Complete) archive containing the manifest and all source files.
+
+### Auto-Generating Provides
+```bash
+usm manifest autoprovides [--replace] [build-path]
+```
+Scans build output to automatically generate the `provides` section.
+
+## Package Validation
+
+USM validates manifests for:
+- Required field presence
+- Correct license categories
+- Valid resource references
+- Proper dependency satisfaction
+- Executable script permissions
+
+## Best Practices
+
+### Version Management
+Use semantic versioning: `MAJOR.MINOR.PATCH+PACKAGE_VERSION`
+- Increment MAJOR for incompatible changes
+- Increment MINOR for new features
+- Increment PATCH for bug fixes
+- Add `+N` for packaging revisions
+
+### Dependency Management
+- Specify minimal required dependencies
+- Use appropriate resource types
+- Separate runtime, build, and management dependencies
+- Verify dependency satisfaction before distribution
+
+### Resource Provision
+- Use `as-expected` for standard file locations
+- Specify exact paths for non-standard installations
+- Include all necessary files in `provides`
+- Use appropriate resource types
+
+### Script Management
+- Make all scripts executable
+- Use proper exit codes
+- Handle script arguments correctly
+- Test scripts in isolation
+
+## Repository Integration
+
+Packages can be distributed through USM repositories using:
+- `PACKAGES.usml`: Package listing files
+- `Repo.usmr`: Repository metadata
+- Cryptographic signatures for security
+
+## Troubleshooting
+
+Common issues and solutions:
+- Missing dependencies: Verify all resource references exist
+- Build failures: Check executable script permissions and paths
+- Installation errors: Ensure `provides` matches actual build output
+- Validation failures: Review JSON syntax and required fields
+
+---
+
+This guide provides package maintainers with essential information for creating, managing, and distributing USM packages effectively.

slopdocs/structure.usm.manifest.resource-types.md

@@ -0,0 +1,197 @@
+# USM Resource Types Reference
+
+## Overview
+Resource references identify specific system resources using the format `[resource-type]:[resource-name]`. The resource type determines where the resource is located on the filesystem.
+
+## Resource Types
+
+### rootpath
+Location: Filesystem root (`/[resource-name]`)
+Used for: Root-level files and directories
+Example: `rootpath:boot/config`
+
+### path
+Location: `/usr/[resource-name]`
+Used for: General files in /usr hierarchy
+Example: `path:local/bin/custom-tool`
+
+### opt
+Location: `/opt/[resource-name]`
+Used for: Optional software packages
+Example: `opt:myapp/bin/myapp`
+
+### res
+Location: `/usr/share/[resource-name]`
+Used for: Shared data files
+Example: `res:myapp/themes/default.theme`
+
+### cfg
+Location: `/etc/[resource-name]`
+Used for: Configuration files
+Example: `cfg:myapp/config.conf`
+
+### bin
+Location: System PATH directories
+Used for: Executable binaries
+Example: `bin:myapp`
+
+### sbin
+Location: `/usr/sbin` or `/sbin`
+Used for: System administration binaries
+Example: `sbin:myapp-daemon`
+
+### lib
+Location: System library paths
+Used for: Shared libraries
+Example: `lib:libmyapp.so.1`
+
+### libexec
+Location: `/usr/libexec`
+Used for: Library executables
+Example: `libexec:myapp-helper`
+
+### libres
+Location: `/usr/lib`, `/usr/lib64`, `/lib`, or `/lib64`
+Used for: Library resource files
+Example: `libres:myapp/plugins/extension.so`
+
+### info
+Location: `/usr/share/info`
+Used for: GNU info documentation
+Example: `info:myapp.info`
+
+### man
+Location: `/usr/share/man`
+Used for: Manual pages
+Example: `man:myapp.1`
+
+### locale
+Location: `/usr/share/locale`
+Used for: Localization files
+Example: `locale:fr/LC_MESSAGES/myapp.mo`
+
+### app
+Location: `/usr/share/applications`
+Used for: Desktop application entries
+Example: `app:myapp.desktop`
+
+### inc
+Location: `/usr/include`
+Used for: C/C++ header files
+Example: `inc:myapp.h`
+
+### pc
+Location: pkg-config paths
+Used for: pkg-config files
+Example: `pc:myapp.pc`
+
+### vapi
+Location: `/usr/share/vala/vapi` or `/usr/share/vala-0.56/vapi`
+Used for: Vala API files
+Example: `vapi:myapp.vapi`
+
+### gir
+Location: `/usr/share/gir`
+Used for: GObject Introspection files
+Example: `gir:MyApp-1.0.gir`
+
+### typelib
+Location: `/usr/lib64/girepository-1.0`, `/usr/lib/girepository-1.0`, `/lib64/girepository-1.0`, or `/lib/girepository-1.0`
+Used for: GObject typelib files
+Example: `typelib:MyApp-1.0.typelib`
+
+### tag
+Location: `/usr/share/usm-tags/[hierarchical-path].tag`
+Used for: USM system tags
+Example: `tag:category.subcategory.feature`
+
+## Resource Reference Format
+
+Resource references follow the pattern: `type:name`
+
+Examples:
+- `bin:ls` - The ls executable
+- `lib:libc.so.6` - The libc shared library
+- `man:ls.1` - Manual page for ls
+- `cfg:myapp.conf` - Configuration file for myapp
+- `app:myapp.desktop` - Desktop entry for myapp
+
+## Path Resolution
+
+USM resolves resource paths in this order:
+1. Check standard system locations for the resource type
+2. Use environment variables when set (USM_PREFIX, USM_LIBDIR, etc.)
+3. Fall back to default paths
+
+## Common Usage Patterns
+
+### Development Libraries
+```json
+{
+  "provides": {
+    "lib:libmyapp.so": "as-expected",
+    "inc:myapp.h": "as-expected",
+    "pc:myapp.pc": "as-expected"
+  }
+}
+```
+
+### Applications
+```json
+{
+  "provides": {
+    "bin:myapp": "as-expected",
+    "app:myapp.desktop": "as-expected",
+    "res:myapp/icons/hicolor/256x256/apps/myapp.png": "as-expected"
+  }
+}
+```
+
+### Development Tools
+```json
+{
+  "provides": {
+    "bin:myapp-tool": "as-expected",
+    "man:myapp-tool.1": "as-expected",
+    "libexec:myapp-helper": "as-expected"
+  }
+}
+```
+
+## Dependency Specification
+
+Resources are specified as dependencies using the same format:
+
+```json
+{
+  "depends": {
+    "runtime": ["lib:libglib-2.0.so", "lib:libc.so.6"],
+    "build": ["bin:gcc", "pc:glib-2.0.pc"],
+    "manage": ["bin:bash"]
+  }
+}
+```
+
+## Resource Validation
+
+USM validates resource references by:
+- Checking existence in expected locations
+- Verifying file permissions
+- Validating resource type formats
+- Ensuring path accessibility
+
+## Environment Variables
+
+USM respects these environment variables for path customization:
+- `USM_DESTDIR`: Destination directory
+- `USM_PREFIX`: Installation prefix
+- `USM_LIBDIR`: Library directory
+- `USM_BINDIR`: Binary directory
+- `USM_INCLUDEDIR`: Include directory
+- `USM_DATADIR`: Data directory
+- `USM_MANDIR`: Manual page directory
+- `USM_TAGSDIR`: Tags directory
+
+---
+
+This reference provides complete specification for all USM resource types and their usage patterns.

slopdocs/utility.usm.manifest.autoprovides.md

@@ -0,0 +1,234 @@
+# USM Manifest Autoprovides Command
+
+## Overview
+The `usm manifest autoprovides` command automatically generates the `provides` section of MANIFEST.usm by scanning build output. This tool helps package maintainers ensure all installed files are properly declared.
+
+## Usage
+
+```bash
+usm manifest autoprovides [--replace] [build-path]
+```
+
+### Arguments
+- `build-path`: Directory containing build output (optional, auto-generated if not provided)
+
+### Options
+- `--replace`: Update MANIFEST.usm file with generated provides section
+
+## Process
+
+### 1. Build Execution
+The command first builds the package using the specified build script:
+- Runs `usm manifest build` with silent output
+- Captures build progress for display
+- Uses temporary build directory if not specified
+
+### 2. Installation Simulation
+Build output is installed to temporary directory:
+- Creates temporary install directory
+- Runs package's install script if present
+- Uses standard USM installation process
+
+### 3. Filesystem Scanning
+The temporary install directory is scanned recursively:
+- Traverses all files and directories
+- Identifies resource types based on file locations
+- Maps file paths to appropriate resource references
+
+### 4. Resource Type Detection
+Files are classified using these rules:
+- `/usr/bin/*` → `bin:filename`
+- `/usr/sbin/*` → `sbin:filename`
+- `/usr/lib*/*` → `lib:filename` or `libres:filename`
+- `/usr/include/*` → `inc:filename`
+- `/usr/share/applications/*` → `app:filename`
+- `/usr/share/man/*` → `man:filename`
+- `/usr/share/info/*` → `info:filename`
+- `/usr/share/locale/*` → `locale:filename`
+- `/usr/share/vala*/vapi/*` → `vapi:filename`
+- `/usr/share/gir*/*` → `gir:filename`
+- `/usr/lib*/girepository-1.0/*` → `typelib:filename`
+- `/usr/lib*/pkgconfig/*` → `pc:filename`
+- `/etc/*` → `cfg:filename`
+- `/opt/*` → `opt:filename`
+- `/usr/share/usm-tags/*` → `tag:filename`
+- Other `/usr/share/*` → `res:filename`
+- All other paths → `rootpath:filename` (fallback when no specific type matches)
+
+### 5. Output Generation
+Results are formatted as JSON provides section:
+
+```json
+"provides": {
+  "bin:myapp": "as-expected",
+  "lib:libmyapp.so": "as-expected",
+  "inc:myapp.h": "as-expected",
+  "app:myapp.desktop": "as-expected",
+  "res:myapp/icons/hicolor/256x256/apps/myapp.png": "as-expected",
+  "rootpath:boot/config": "as-expected"
+}
+```
+
+## Examples
+
+### Basic Usage
+Generate provides section and display to stdout:
+```bash
+usm manifest autoprovides
+```
+
+### With Custom Build Directory
+Use specific build directory:
+```bash
+usm manifest autoprovides /tmp/myapp-build
+```
+
+### Replace in Manifest
+Update MANIFEST.usm file directly:
+```bash
+usm manifest autoprovides --replace
+```
+
+### With Custom Build Directory and Replace
+Combine options:
+```bash
+usm manifest autoprovides --replace /tmp/myapp-build
+```
+
+## Output Format
+
+### Console Output
+Without `--replace`, command outputs JSON provides section:
+```json
+"provides": {
+  "bin:myapp": "as-expected",
+  "lib:libmyapp.so": "as-expected",
+  "rootpath:custom-file": "as-expected"
+}
+```
+
+### File Update
+With `--replace`, command:
+- Updates existing MANIFEST.usm file
+- Preserves all other manifest fields
+- Replaces only the provides section
+- Creates backup of original file
+
+## Integration Workflow
+
+### 1. Initial Package Creation
+```bash
+usm scaffold myapp meson vala
+```
+
+### 2. Build and Test
+```bash
+usm manifest build /tmp/build
+```
+
+### 3. Generate Provides
+```bash
+usm manifest autoprovides --replace /tmp/build
+```
+
+### 4. Review and Customize
+Edit MANIFEST.usm to:
+- Add custom file locations
+- Remove unwanted resources
+- Specify non-standard installations
+
+### 5. Final Testing
+```bash
+usm manifest install /tmp/build
+```
+
+## Best Practices
+
+### When to Use
+- After implementing build system
+- When adding new files to package
+- After changing installation paths
+- Before package release
+
+### Review Required
+Always review generated provides for:
+- Missing important files
+- Incorrect resource types
+- Unwanted temporary files
+- Non-standard file locations
+
+### Manual Overrides
+Some files require manual specification:
+- Configuration files in custom locations
+- Data files outside standard paths
+- Generated files created during runtime
+- Optional components
+
+### Common Adjustments
+```json
+{
+  "provides": {
+    "bin:myapp": "as-expected",
+    "lib:libmyapp.so": "as-expected",
+    "cfg:myapp.conf": {"pathBase": "install", "path": "etc/myapp.conf", "type": "reg"},
+    "res:myapp/default-config": {"pathBase": "source", "path": "config/default.json", "type": "reg"},
+    "rootpath:boot/loader.conf": {"pathBase": "install", "path": "boot/loader.conf", "type": "reg"}
+  }
+}
+```
+
+## Troubleshooting
+
+### Empty Provides
+If no resources are detected:
+- Check build completed successfully
+- Verify install script exists and works
+- Ensure files are installed to correct locations
+- Check file permissions
+
+### Incorrect Resource Types
+If files are misclassified:
+- Verify build follows FHS standards
+- Check for custom installation paths
+- Review build system configuration
+- Consider manual overrides
+
+### Build Failures
+When autoprovides fails during build:
+- Check build dependencies are satisfied
+- Verify build script is executable
+- Review build script syntax
+- Test build manually first
+
+### Permission Issues
+If file update fails:
+- Check MANIFEST.usm file permissions
+- Verify directory write access
+- Ensure file is not locked by other processes
+- Run with appropriate user permissions
+
+## Advanced Usage
+
+### Custom Resource Mapping
+For non-standard layouts, manually edit generated provides:
+```json
+{
+  "provides": {
+    "bin:myapp": "as-expected",
+    "lib:libmyapp.so": {"pathBase": "build", "path": "custom/lib/libmyapp.so", "type": "reg"},
+    "res:myapp/data": {"pathBase": "source", "path": "data/*", "type": "reg"},
+    "rootpath:etc/custom-config": {"pathBase": "source", "path": "config/custom.conf", "type": "reg"}
+  }
+}
+```
+
+### Selective Resource Inclusion
+Remove unwanted resources from generated output:
+- Delete lines for temporary files
+- Remove development-only resources
+- Exclude documentation if not needed
+- Filter out test files
+
+---
+
+This command provides package maintainers with automated tools for generating accurate manifest provides sections.

src/cli/Manifest.vala

@@ -549,9 +549,9 @@ private static string get_local_resource_type(string path) {
         }
     }
     
-    // If no matches found, default to "res"
+    // If no matches found, default to "rootpath"
     if (matching_types.peek_count() == 0) {
-        return "res";
+        return "rootpath";
     }
     
     // Find the type with the fewest directory traversals