nephio-project · lovesprung · Jul 24, 2025 · Jul 31, 2025 · Jul 31, 2025 · Jul 31, 2025
diff --git a/content/en/docs/porch/user-guides/porchctl-cli-guide.md b/content/en/docs/porch/user-guides/porchctl-cli-guide.md
@@ -97,7 +97,9 @@ package content. The matching resources share the same `name` (as well as API gr
 
 To use Porch with a Git repository, you will need:
 
-* A Git repository for your blueprints.
+* A Git repository for your blueprints. An otherwise empty repository with an
+  initial commit works best. The initial commit is required to establish the
+  `main` branch.
 * If the repository requires authentication you will require either
   - A [Personal Access Token](https://github.com/settings/tokens) (when using GitHub repository) for Porch to authenticate
     with the repository if the repository. Porch requires the 'repo' scope.
@@ -360,7 +362,13 @@ items:
 ...
 ```
 
-Or, the package revision contents can be saved on local disk for direct introspection or editing:
+One of the driving motivations for the Package Orchestration service is enabling
+WYSIWYG authoring of packages, including their contents, in highly usable UIs.
+Porch therefore supports reading and updating package *contents*.
+
+In addition to using a [UI](https://kpt.dev/guides/namespace-provisioning-ui/) with Porch, we
+can change the package contents by pulling the package from Porch onto the local
+disk, make any desired changes, and then pushing the updated contents to Porch.
 
 ```bash
 $ porchctl rpkg pull -n porch-demo porch-test.network-function.innerhome ./innerhome
@@ -374,6 +382,86 @@ $ find innerhome
 ./innerhome/package-context.yaml
 ```
 
+The command downloaded the `innerhome/v1` package revision contents and saved
+them in the `./innerhome` directory. Now you will make some changes.
+
+First, note that even though Porch updated the namespace name (in
+`namespace.yaml`) to `innerhome` when the package was cloned, the `README.md`
+was not updated. Let's fix it first.
+
+Open the `README.md` in your favorite editor and update its contents, for
+example:
+
+```
+# innerhome
+
+## Description
+kpt package for provisioning Innerhome namespace
+```
+
+In the second change, add a new mutator to the `Kptfile` pipeline. Use the
+[set-labels](https://catalog.kpt.dev/set-labels/v0.1/) function which will add
+labels to all resources in the package. Add the following mutator to the
+`Kptfile` `pipeline` section:
+
+```yaml
+  - image: gcr.io/kpt-fn/set-labels:v0.1.5
+    configMap:
+      color: orange
+      fruit: apple
+```
+
+The whole `pipeline` section now looks like this:
+
+```yaml
+pipeline:
+  mutators:
+  - image: gcr.io/kpt-fn/set-namespace:v0.4.1
+    configPath: package-context.yaml
+  - image: gcr.io/kpt-fn/apply-replacements:v0.1.1
+    configPath: update-rolebinding.yaml
+  - image: gcr.io/kpt-fn/set-labels:v0.1.5
+    configMap:
+      color: orange
+      fruit: apple
+```
+
+Save the changes and push the package contents back to the server:
+
+```sh
+# Push updated package contents to the server
+$ porchctl rpkg push -n porch-demo porch-test.network-function.innerhome ./innerhome -ndefault
+```
+
+Now, pull the contents of the package revision again, and inspect one of the
+configuration files.
+
+```sh
+# Pull the updated package contents to local drive for inspection:
+$ porchctl rpkg pull -n porch-demo porch-test.network-function.innerhome ./updated-innerhome -ndefault
+
+# Inspect updated-innerhome/namespace.yaml
+$ cat updated-innerhome/namespace.yaml 
+
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: innerhome
+  labels:
+    color: orange
+    fruit: apple
+spec: {}
+```
+
+The updated namespace now has new labels! What happened?
+
+Whenever package is updated during the authoring process, Porch automatically
+re-renders the package to make sure that all mutators and validators are
+executed. So when we added the new `set-labels` mutator, as soon as we pushed
+the updated package contents to Porch, Porch re-rendered the package and
+the `set-labels` function applied the labels we requested (`color: orange` and
+`fruit: apple`).
+
 ## Authoring Packages
 
 Several commands in the `porchctl rpkg` group support package authoring:
@@ -408,7 +496,7 @@ Additional flags supported by the `porchctl rpkg init` command are:
 * `--site` - Link to page with information about the package revision.
 
 
-Use `porchctl rpkg clone` command to create a _downstream_ package revision by cloning an _upstream_ package revision:
+Use `porchctl rpkg clone` command to create a _downstream_ package revision by cloning an _upstream_ package revision. You can find out more about the _upstream_ and _downstream_ sections of the `Kptfile` in a [Getting a Package](https://kpt.dev/book/03-packages/01-getting-a-package).
 
 ```bash
 $ porchctl rpkg clone porch-test.new-package.my-workspace new-package-clone --repository=porch-deployment -n porch-demo
@@ -420,6 +508,15 @@ NAME                                    PACKAGE             WORKSPACENAME   REVI
 porch-deployment.new-package-clone.v1   new-package-clone   v1              0          false    Draft       porch-deployment
 ```
 
+{{% alert title="Note" color="primary" %}}
+ A cloned package must be created in a repository in the same namespace as
+ the source package. Cloning a package with the Package Orchestration Service
+ retains a reference to the upstream package revision in the clone, and
+ cross-namespace references are not allowed. Package revisions in repositories
+ in other namespaces can be cloned using a reference directly to the underlying
+ oci or git repository as described below.
+{{% /alert %}}
+
 `porchctl rpkg clone` can also be used to clone package revisions that are in repositories not registered with Porch, for
 example:
 
@@ -463,6 +560,13 @@ $ porchctl rpkg get porch-test.network-function.great-outdoors -n porch-demo
 NAME                                         PACKAGE            WORKSPACENAME    REVISION   LATEST   LIFECYCLE   REPOSITORY
 porch-test.network-function.great-outdoors   network-function   great-outdoors   0          false    Draft       porch-test
 ```
+Unlike `clone` of a package which establishes the upstream-downstream
+relationship between the respective packages, and updates the `Kptfile`
+to reflect the relationship, the `copy` command does *not* change the
+upstream-downstream relationships. The copy of a package shares the same
+upstream package as the package from which it was copied. Specifically,
+in this case both packages have identical contents,
+including upstream information, and differ in revision only.
 
 The `porchctl rpkg pull` and `porchctl rpkg push` commands can be used to update the resources (package revision contents) of a package _draft_:
 

diff --git a/content/en/docs/porch/user-guides/preparing-the-environment.md b/content/en/docs/porch/user-guides/preparing-the-environment.md
@@ -873,6 +873,60 @@ status:
 ```
 </details>
 
+## The porchctl command
+
+The `porchtcl` command is an administration command for acting on Porch `Repository` (repo) and `PackageRevision` (rpkg)
+CRs. See its [documentation for usage information](porchctl-cli-guide.md).
+
+Check that <code>porchctl</code> lists our repositories:</summary>
+
+```bash
+porchctl repo -n porch-demo get
+NAME                  TYPE   CONTENT   DEPLOYMENT   READY   ADDRESS
+edge1                 git    Package   true         True    http://172.18.255.200:3000/nephio/edge1.git
+external-blueprints   git    Package   false        True    https://github.com/nephio-project/free5gc-packages.git
+management            git    Package   false        True    http://172.18.255.200:3000/nephio/management.git
+```
+
+<details>
+<summary>Check that porchctl lists our remote packages (PackageRevisions):</summary>
+
+```
+porchctl rpkg -n porch-demo get
+NAME                                                           PACKAGE              WORKSPACENAME   REVISION   LATEST   LIFECYCLE   REPOSITORY
+external-blueprints-922121d0bcdd56bfa8cae6c375720e2b5f358ab0   free5gc-cp           main            main       false    Published   external-blueprints
+external-blueprints-dabbc422fdf0b8e5942e767d929b524e25f7eef9   free5gc-cp           v1              v1         true     Published   external-blueprints
+external-blueprints-716aae722092dbbb9470e56079b90ad76ec8f0d5   free5gc-operator     main            main       false    Published   external-blueprints
+external-blueprints-d65dc89f7a2472650651e9aea90edfcc81a9afc6   free5gc-operator     v1              v1         false    Published   external-blueprints
+external-blueprints-9fee880e8fa52066f052c9cae7aac2e2bc1b5a54   free5gc-operator     v2              v2         false    Published   external-blueprints
+external-blueprints-91d60ee31d2d0a1a6d5f1807593d5419434accd3   free5gc-operator     v3              v3         false    Published   external-blueprints
+external-blueprints-21f19a0641cf520e7dc6268e64c58c2c30c27036   free5gc-operator     v4              v4         false    Published   external-blueprints
+external-blueprints-bf2e7522ee92680bd49571ab309e3f61320cf36d   free5gc-operator     v5              v5         true     Published   external-blueprints
+external-blueprints-c1b9ecb73118e001ab1d1213e6a2c94ab67a0939   free5gc-upf          main            main       false    Published   external-blueprints
+external-blueprints-5d48b1516e7b1ea15830ffd76b230862119981bd   free5gc-upf          v1              v1         true     Published   external-blueprints
+external-blueprints-ed97798b46b36d135cf23d813eccad4857dff90f   pkg-example-amf-bp   main            main       false    Published   external-blueprints
+external-blueprints-ed744bfdf4a4d15d4fcf3c46fde27fd6ac32d180   pkg-example-amf-bp   v1              v1         false    Published   external-blueprints
+external-blueprints-5489faa80782f91f1a07d04e206935d14c1eb24c   pkg-example-amf-bp   v2              v2         false    Published   external-blueprints
+external-blueprints-16e2255bd433ef532684a3c1434ae0bede175107   pkg-example-amf-bp   v3              v3         false    Published   external-blueprints
+external-blueprints-7689cc6c953fa83ea61283983ce966dcdffd9bae   pkg-example-amf-bp   v4              v4         false    Published   external-blueprints
+external-blueprints-caff9609883eea7b20b73b7425e6694f8eb6adc3   pkg-example-amf-bp   v5              v5         true     Published   external-blueprints
+external-blueprints-00b6673c438909975548b2b9f20c2e1663161815   pkg-example-smf-bp   main            main       false    Published   external-blueprints
+external-blueprints-4f7dfbede99dc08f2b5144ca550ca218109c52f2   pkg-example-smf-bp   v1              v1         false    Published   external-blueprints
+external-blueprints-3d9ab8f61ce1d35e264d5719d4b3c0da1ab02328   pkg-example-smf-bp   v2              v2         false    Published   external-blueprints
+external-blueprints-2006501702e105501784c78be9e7d57e426d85e8   pkg-example-smf-bp   v3              v3         false    Published   external-blueprints
+external-blueprints-c97ed7c13b3aa47cb257217f144960743aec1253   pkg-example-smf-bp   v4              v4         false    Published   external-blueprints
+external-blueprints-3bd78e46b014dac5cc0c58788c1820d043d61569   pkg-example-smf-bp   v5              v5         true     Published   external-blueprints
+external-blueprints-c3f660848d9d7a4df5481ec2e06196884778cd84   pkg-example-upf-bp   main            main       false    Published   external-blueprints
+external-blueprints-4cb00a17c1ee2585d6c187ba4d0211da960c0940   pkg-example-upf-bp   v1              v1         false    Published   external-blueprints
+external-blueprints-5903efe295026124e6fea926df154a72c5bd1ea9   pkg-example-upf-bp   v2              v2         false    Published   external-blueprints
+external-blueprints-16142d8d23c1b8e868a9524a1b21634c79b432d5   pkg-example-upf-bp   v3              v3         false    Published   external-blueprints
+external-blueprints-60ef45bb8f55b63556e7467f16088325022a7ece   pkg-example-upf-bp   v4              v4         false    Published   external-blueprints
+external-blueprints-7757966cc7b965f1b9372370a4b382c8375a2b40   pkg-example-upf-bp   v5              v5         true     Published   external-blueprints
+```
+</details>
+
+The output above is similar to the output of `kubectl get packagerevision -n porch-demo` above.
+
 ## Creating a blueprint in Porch
 
 ### Blueprint with no Kpt pipelines