README.md in Package

Why a README is Required

The manifest.json is machine-readable — it tells the import engine what to install. The README.md is human-readable — it tells the administrator what they are installing and what to expect.

A good README prevents surprises: it explains what workflows will appear, what forms will be created, what permissions are needed, and what the package expects from the environment.

Auto-Generated vs. Author-Written

When you export a package, the system auto-generates a minimal README based on the manifest. For internal use, this is usually sufficient. For marketplace publishing, you are expected to replace the auto-generated README with a well-written, detailed document.

Auto-Generated README Template

# Employee Onboarding Suite

**Version:** 2.1.0
**Package Type:** workflow-package
**Exported By:** engineer@acme.com
**Exported At:** 2026-05-25T09:00:00Z

## What This Package Installs

This package contains 5 artifacts:

| Type | Name | Version |
|------|------|---------|
| ProcessDefinition | EmployeeOnboarding | 2.1.0 |
| ThreadDefinition | ApprovalSubflow | 1.0.0 |
| AtlasForm | EmployeeForm | 1.3.0 |
| RuleSet | ApprovalRules | 1.0.0 |
| EntitySchema | EmployeeSchema | 1.0.0 |

## Prerequisites

None declared.

## Installation

Import this package using the InstallHub import API:
POST /api/installhub/packages/import

## Checksum

sha256:3a9f1c4e8d2b7f6a1e5c9d3b0a4f8e2c7d1a6b9e3f5c8d2a0b7e4f1c9d3a6b0

Recommended README Structure

For marketplace and shared packages, use this structure:

# {Package Name}

{One-line description of what this package does}

## Overview

{2-4 sentences explaining the package purpose, who should use it, and what problem it solves.}

## What This Package Installs

{Brief description of each artifact type included}

- **Workflows**: {list key workflow names}
- **Forms**: {list key form names}
- **Rules**: {list key rule sets}
- **Entities**: {list entity schemas}

## Prerequisites

- **BizFirstGO platform**: {minimum version}
- **Required packages**: {other packages that must be installed first}
- **Permissions**: {roles or permissions the installing user must have}
- **Configuration**: {environment variables or settings that must exist}

## Post-Install Configuration

{Step-by-step configuration required after installation}

1. Navigate to {location} and configure {setting}
2. Assign the "{workflow name}" workflow to the appropriate tenant role
3. {etc.}

## Compatibility

| Platform Version | Package Version | Status |
|-----------------|-----------------|--------|
| 4.x | 2.x | Supported |
| 3.x | 1.x | Legacy    |

## Changelog

### {version} ({date})
- {what changed}

## Support

{Contact email or support URL}

## License

{SPDX license identifier or "Proprietary"}

Required Sections for Certified Status

To achieve Certified trust level on the marketplace, the README must include all of these sections:

README Size Limit

The README must not exceed 64 KB (approximately 64,000 characters). Images should not be embedded as Base64 — use external URLs instead (HTTPS only).